Onboarding: Laboratoria Code Squads

Piloto de colaboración en publicación de herramientas con Laboratoria

Guía de acompañamiento para laboratorians

Contenido 📚

• ¿Qué es Código para el Desarrollo?

• ¿Cuál es el objetivo del piloto?

• ¿Cuáles serán los canales de comunicación?

• ¿Cuáles son las etapas o estructura de actividades del piloto? y ¿cuánto tiempo durarán estas etapas?

• ¿Cómo contribuirán las laboratorians en este piloto?

  • Perfiles
    • Revisoras de repos
    • Generadoras de contenido

• ¿En qué consiste la revisión de repos?

  • Documentación
    • Puntos de trabajo en documentación
  • Evaluación técnica
    • Puntos de trabajo en la evaluación técnica
  • Licenciamiento
    • Puntos de trabajo en el licenciamiento

• ¿En qué consiste la generación de contenidos?

  • Puntos de trabajo en la generación de contenido

• Reflexiones e ideas

• Reconocimientos a laboratorians

¿Qué es Código para el Desarrollo?

Desde el BID promovemos la idea que el software es un producto de conocimiento, y como tal debe ser compartido. Por eso lanzamos Código para el Desarrollo, una iniciativa que sirve como plataforma para compartir recursos y software de código abierto y también conectar las diversas comunidades que apoyan la visión que el software es un bien público.

¿Cuál es el objetivo del piloto?

El objetivo principal es descentralizar el proceso de evaluación de herramientas que se suman al catálogo de la web code.iadb.org.

Esto con el fin de mejorar la eficiencia en el proceso de publicación y recibir finalmente retroalimentación, reflexiones e ideas del proceso con una perspectiva nueva y fresca.

Creemos que mientras más abramos nuestro proceso podremos aprender más colaborativamente.

A su vez, esperamos que para las laboratorians la experiencia de coordinar en interactuar con los equipos dueños de las herramientas sea enriquecedor.

Cabe señalar que en esta oportunidad solo nos centraremos en repos en español.

¿Cuáles serán los canales de comunicación?

Interacción con el equipo de Código para el Desarrollo y los equipos de las herramientas a revisar?

Usaremos 3 canales de comunicación principales:

• Github: Interacción con equipos owners: Las chicas que verán las revisiones a los repos de las herramientas (evaluación técnica, documentación y licenciamiento) tendrán que interactuar con los equipos en la sección de issues en los repos oficiales de las mismas.

Interacción con equipo de Código para el Desarrollo: Aceptaremos issues en el repo de onboarding y estaremos atentas a nuevas discusiones en el team Laboratoria Code Squads.

• Slack: Hemos creado el slack BID-COMUNIDADES el cual será nuestro canal de interacción principal entre el equipo de Código para el Desarrollo y las Laboratorian durante este piloto.

Los canales que encontrarán en slack son:

• canales por herramienta asignada: Podrán interactuar con las integrantes de su equipo allí.

• #anuncios: postearemos anuncios oficiales de la piloto.

• #dudas: Estaremos atentos a sus consultas en este canal.

• #random: cosas random que quieran compartir con todas.

• #General: Recursos, comentarios, testimonios, apreciaciones, etc sobre la piloto que quieran compartir.

• Correo electrónico:

Las chicas cuya asignación es la de generar contenido (vitrina y blog sobre la herramienta) tendrán que usar este canal de comunicación para facilitar la creación de contenido con las personas designadas en los equipos owners.

Siempre poner en copia a Laura Paonessa ([email protected]), Michelle Marshall ([email protected]) y a [email protected].

Para cualquier otra consulta que no nos puedan hacer vía slack pueden comunicarse con nosotros al correo [email protected].

¿Cuáles son las etapas o estructura de actividades del piloto? y ¿cuánto tiempo durarán estas etapas?

• Kickoff Meeting - Jueves 23 de abril 2020

• Contacto con equipos owners y acceso a Slack - Inicio Lunes 27 de abril 2020

• Interacción con equipos owners en Github - Del jueves 30 de abril al 22 de mayo

• Generación de contenido sobre herramientas - Del jueves 30 de abril al 22 de mayo

• Reflexiones e ideas - Mandaremos formularios semanalmente para recopilar información.

• Reconocimientos a laboratorians - Semana del 25 de mayo.

Tendremos 4 videollamadas durante las 4 semanas de este piloto.

Se realizarán en las siguientes fechas y horas en Jitsi meet, dejaremos el link al la videollamada en el canal #anuncios de slack

• Jueves 30 de abril, 4pm - Preguntas sobre Onboarding
• Martes 05 de mayo, 4pm - ¿Cómo vamos? Avances y preguntas
• Martes 12 de mayo, 4pm - ¿Cómo vamos? Avances y preguntas
• Martes 10 de mayo, 4pm - ¿Cómo vamos? Avances y preguntas

¿Cómo contribuirán las laboratorians en este piloto?

Previa coordinación hemos identificado y contactado con los equipos de herramientas candidatas a ser publicadas en code.iadb.org, algunas serán publicadas y otras será mejoradas.

Hemos hecho la distribución de las herramientas entre 20 laboratorians que se inscribieron como colaboradoras en este piloto, podrán ver sus asignaciones en slack y también se las enviaremos por correo.

Perfiles:

Hemos asignado a las laboratorians en sus respectivos equipos de trabajo asignándoles a la vez un perfil de trabajo. Las principales tareas de estos perfiles son:

Revisoras de repos

Se encargarán de la revisión de Documentación, Evaluación técnica y licenciamiento.

Contrastará los estándares de documentación y evaluación técnica y licenciamiento de nuestra guía y levantarán issues respecto a lo que falte en los repos oficiales en github de las herramientas asignadas. A su vez, estos issues tendrán que ser supervisados por esta laboratorian hasta donde sus capacidades se lo permita.

https://el-bid.github.io/guia-de-publicacion/

Generadoras de contenido

Coordinará con el equipo de comunicación de la herramienta para la creación de la vitrina de la herramienta en code.iadb.org siguiendo el template que ya manejamos y posteriormente también coordinará con Michelle Marshall, editora del Blog Abierto al Público la creación de un blog sobre la herramienta, enfocándose en la historia, impacto y posible reutilización de la misma.

https://blogs.iadb.org/conocimiento-abierto/es/

¿En qué consiste la revisión de repos?

En la iniciativa revisamos los repos de las herramientas bajo tres pilares:

Documentación:

Aunque no existe un formato estándar para abordar la documentación de herramientas de código abierto, pero en nuestra plantilla de repositorio podrán encontrar las secciones necesarias más comunes para disponer de un README.md

Opcionalmente, esta información puede ir en otros documentos o archivos, pero estos recursos deben estar siempre referenciados en el README.md

Puntos de trabajo en documentación:

• Revisar que el readme.md del repo público tenga las secciones que detallamos en la guía de publicación. https://el-bid.github.io/guia-de-publicacion/documents/documentacion/, contamos con una plantilla de README.md para que pueda ser más fácil hacer esta revisión. https://github.com/EL-BID/Plantilla-de-repositorio/blob/master/README.md

• Generar un issue tipo checklist en el repo oficial de la herramienta que está siendo revisada sobre la información faltante en el README.md. En este issue se mencionará también qué parte de lo faltante podrá ser resuelta por la laboratorian, siempre teniendo en cuenta su capacidad para hacerlo. Para que posteriormente se genere un pull request de los puntos que se ofrecieron a resolver. Esto último reafirmamos, NO es obligatorio, pero en caso de que se pueda hacer ya hemos dado aviso a los equipos owners para que estén atentos a las sugerencias. El issue estará clasificado por los owners por los tags help wanted y documentación.

• Si la documentación se encontrase en inglés, también se agregará como un punto en el checklist la traducción de este contenido al español.

• Usar esta plantilla de issue de documentación. https://github.com/BID-COMUNIDADES/Onboarding-Code-squads-Laboratoria/blob/master/plantilla_Issue_Documentacion.md Esto ayudará a que veamos el evance ya que estará tageada la cuenta oficial del banco.

• Conforme vaya avanzando la interacción con los equipos se ira cerrando este issue de documentación, esto puede pasar durante la piloto o posteriomente a la piloto.

Evaluación técnica:

Al igual que la documentación, para la evaluación técnica de herramientas de código abierto no existe un estándar definido, pero bajo la iniciativa hemos identificado factores clave para empezar a evaluar las herramientas que publicamos. Recordemos antes de iniciar que cada herramienta tiene sus propias particularidades y que nos encontramos muy abiertos a recibir retroalimentación en especial en esta parte del proceso de publicación.

Revisar la guía de publicación en la sección de evaluación técnica, allí encontrarán los puntos que consideramos solicitar a los equipos owners de las herramientas.

https://el-bid.github.io/guia-de-publicacion/documents/evaluacion/

Puntos de trabajo en la evaluación técnica:

• Agregar el microservicio de reportes de evaluación estática de código de Sonarcloud Será obligatorio que todas las herramientas de la piloto tengan un reporte de evaluación estática de código. Lo ideal en este punto es que el repositorio tenga vinculado un servicio que ofrezca esta opción, para esto, el equipo owner tendrá que registrarse y vincular su cuenta de github con este servicio. Para laboratorians que estén revisando herramientas del BID solo tendrán que contactar con Jesenia Rodríguez para generar el reporte de Sonarcloud ya que el BID ya cuenta con este servicio vinculado.

Nosotros recomendamos SonarCloud por la baja brecha de aprendizaje que ofrece para empezar a usarlo, pero las dejamos decidir si quisieran recomendar otro servicio similar.

Usar este template de issue de evaluación técnica, esto ayudará a que veamos el evance ya que estará tageada la cuenta oficial del BID. https://github.com/BID-COMUNIDADES/Onboarding-Code-squads-Laboratoria/blob/master/plantilla_Issue_evaluacion_tecnica.md

• Agregar el badge del servicio de reportes de evaluación estática visible en el readme.md La mayoría de los servicios que generan reportes estáticos de evaluación de código a su vez generan el markdown de badges para colocar en los repositorios de las herramientas. De esta forma cualquier persona puede ingresar a ver el reporte generado por el último commit de la herramienta.

• Agregar el microservicio de integración continua de código (opcional)

Será opcional que los equipos implementen una herramienta de integración continua de código.Recomendamos recomendamos Travis CI para visibilizar el estado del build (debe estar en estado passing.

Pueden usar cualquier otro microservicio que tenga esa función, a su vez es ideal poder ver el estado del build de manera pública.

https://docs.travis-ci.com/

• Agregar el badge de este servicio visible en el readme.md (opcional) La mayoría de los servicios o herramientas de integración continua de código tiene la opción de generar badges en markdown que pueden insertarse en el readme.md, el cual debe ser agregado de realizarse esta tarea.

• Posibilidad de generar Pull Requests Una vez generado el reporte se podrán visualizar diversos problemas con el código, en este momento la laboratorian observará cual de esos problemas estará en capacidad de resolver generando pull requests, recalcamos que esto último no es obligatorio, pero de realizarse ya hemos dado aviso a los equipos owners de tener especial atención a estas contribuciones.

Licenciamiento:

Si la herramienta fue creada bajo el financiamiento del BID, se presentará la opción de usar la Licencia AM-331-A3, la cual deberá ser agregada en formato markdown en el LICENCE.md

https://github.com/EL-BID/guia-de-publicacion/blob/master/_documents/pages/licenciabid.markdown

Si la herramienta fue creada fuera de un financimiento del BID, pueden usar cualquier licencia de código abierto.

De no tenerla, recomendamos revisar https://choosealicense.com/

Puntos de trabajo en el licenciamiento:

• Revisar que el repo tenga una licencia de código abierto, si el repo no tiene una se sugerirá al equipo owner escoger una.

Puedes usar esta plantilla para solicitar que se agregue https://github.com/BID-COMUNIDADES/Onboarding-Code-squads-Laboratoria/blob/master/plantilla_Issue_licenciamiento.md

¿En qué consiste la generación de contenidos?

En paralelo a la evaluación de repos, las laboratorians que hayan sido asignadas para generar contenido interactuarán con los equipos owner, específicamente con personal que ellos hayan designado para la tarea de acompañamiento en generar contenido sobre la herramienta.

En la iniciativa usamos esta pirámide de contenidos para diferenciar los objetivos de la información que vamos generando con las herramientas:

Puntos de trabajo en la generación de contenido:

• Coordinar por correo electrónico con el encargado(a) de comunicaciones en el equipo owner la creación de la Vitrina de la herramienta en code.iadb.org. Para esto podrá enviar las preguntas de esta plantilla https://github.com/BID-COMUNIDADES/Onboarding-Code-squads-Laboratoria/blob/master/Plantilla_Contenidos.md

• Asegurarse que el contenido de la vitrina sea de utilidad para el público objetivo de la web, los funcionarios(as) públicos de américa latina y el caribe.

• Trabajar con las revisoras de código de su equipo para reutilizar el contenido generado en la vitrinas para que la revisora de documentación pueda mejorar la descripción de la herramienta en el readme.md de la herramienta.

• Coordinar con Laura Paonessa y Michelle Marshall, editora del Blog Abierto al Público la creación de un blog sobre la herramienta, enfocándose en la historia, impacto y posible reutilización de la misma. https://blogs.iadb.org/conocimiento-abierto/es/ Para esto también pueden revisar las preguntas evocadoras que hemos preparado en la plantilla de contenidos. https://github.com/BID-COMUNIDADES/Onboarding-Code-squads-Laboratoria/blob/master/Plantilla_Contenidos.md.

En toda comunicación deberá ser copiada Laura Paonessa ([email protected]), Michelle Marshall ([email protected]) y [email protected].

Reflexiones e ideas

Mandaremos formularios tanto a las laboratorian como a los equipos owner para recopilar información semanalmente durante la piloto.

Reconocimientos a laboratorians

• Diploma de reconocimiento según expertise técnico para las jóvenes que participaron en el piloto.

• Post en el Blog del BID - Abierto al Público - para compartir la experiencia (grupal)

• Recomendación en LinkedIn (Por el BID y los equipos de trabajo de las ciudades)

• Las laboratorian seguirán perteneciendo a la Team en github.