Fase actual:
La temporada de Documentos 2020 finalizó el 15 de marzo de 2021. Consulta el cronograma.
Esta página contiene lineamientos para los escritores técnicos sobre cómo crear un informe de proyecto cuando hayas terminado tu trabajo para la temporada de Documentos de este año.
Cómo enviar el informe del proyecto
Cuando se abra la fase de finalización del proyecto, podrás enviar tu informe del proyecto. Para ello, deberás completar un formulario que estará disponible en la sección de finalización del proyecto de la guía para escritores técnicos.
Información para incluir en el informe del proyecto
En esta sección, se describe el tipo de información que puedes proporcionar en el informe del proyecto. El formulario de informe del proyecto incluirá campos de texto libre, así como preguntas de opción múltiple.
Vincular a tu trabajo
Proporciona un enlace que dirija a una descripción del trabajo que realizaste.
El vínculo debe dirigir a un documento que contenga una breve descripción del trabajo realizado, la documentación que el proyecto de código abierto combinó con su repositorio, un resumen del estado actual del proyecto y una lista de desafíos y aprendizajes.
El vínculo aparecerá en los resultados de la temporada de documentos publicados en el sitio web. Los resultados publicados demuestran el trabajo que realizaste durante el programa. Los resultados publicados también son una buena manera de volver a consultar tu trabajo como parte de tu currículum.
Debes compartir tu enlace con tu mentor y solicitar una revisión antes de enviar el informe del proyecto.
Requisitos para el informe de tu proyecto
Ten en cuenta los siguientes requisitos:
- El contenido vinculado debe facilitar la identificación del trabajo que completaste durante Season of Docs, es decir, los cambios que realizaste o la nueva documentación que escribiste.
- El trabajo debe estar en una ubicación estable. No puedes cambiar la URL después del envío.
Otra persona debería poder usar el contenido que se encuentra en el destino del vínculo (o en el que se hace referencia a él) para aprovechar tu trabajo.
- Si tu trabajo está completo, otras personas deberían poder usarlo.
- Si tu trabajo no está completo, debería quedar claro lo que queda por hacer.
Ejemplos de cómo describir tu trabajo
No tienes que realizar todas estas acciones (ni ninguna), pero estas son algunas formas de cumplir con los requisitos:
Crea una entrada de blog, una página web o un gist público de GitHub que describa el trabajo que realizaste y los vínculos a las confirmaciones que realizaste y los repositorios en los que trabajaste. Si aún hay trabajo por hacer en el proyecto, incluye una descripción de ese trabajo. También puedes compartir momentos destacados o piezas desafiantes.
Esta es la mejor opción porque te permite incluir fácilmente mucha información. Esto es bueno porque muestra claramente el trabajo que hiciste y facilita que otros usen y entiendan tu contribución.
Si usas GitHub y todo tu trabajo está cubierto por una sola solicitud de extracción, puedes usar ese vínculo.
- Asegúrate de que la descripción de la solicitud de extracción esté detallada.
- Asegúrate de que la descripción indique claramente que el trabajo es para la temporada de Documentos.
- Si la solicitud de extracción necesita más trabajo después de que termine la temporada de Documentos, asegúrate de que la última temporada de Documentos tome notas de este hecho.
- Este método para proporcionar un informe del proyecto tiene el beneficio de tener el registro de cambios, una lista de confirmaciones y los comentarios de la opinión, todo en un solo lugar.
Si tu repositorio de GitHub es de un solo propósito para Season of Docs, agrega un archivo README que contenga los detalles de tu trabajo.
Crea una carpeta pública en Google Drive y, luego, incluye todos los parches que creaste.
Crear una hoja de cálculo pública con Hojas de cálculo de Google y enumerar todas tus confirmaciones
Establece vínculos a un solo problema en una herramienta de seguimiento de errores pública, que contenga referencias claras a tu trabajo y cualquier otro elemento apropiado. El problema debería hacer un seguimiento de todo el trabajo que has hecho. Asegúrate de que el problema enumere todas las confirmaciones o de que sea fácil encontrar las confirmaciones de otra manera.
Incluye un vínculo a una diferencia unificada o de contexto de tus cambios. Asegúrate de incluir un encabezado que incluya el nombre de tu proyecto de escritura técnica y quién eres, para que sea útil para otros.
Mal ejemplos de cómo describir tu trabajo
No hagas lo siguiente:
- Establece vínculos a un archivo tarball o ZIP que contenga el código fuente de todo el proyecto o tu directorio de trabajo.
- Vínculo a la parte superior del repositorio de código fuente principal del proyecto. Por ejemplo, si trabajas en Cpython, este vínculo no es útil: https://github.com/python/cpython.
- Vínculo a tu clonación del repositorio de código fuente del proyecto. Esto dificulta ver cuáles son tus cambios porque tu trabajo está mezclado con el de otras personas.
- Vínculo a la descripción de tu proyecto en el sitio web de la temporada de Documentos.
Para los mentores
Ayuda a tu escritor técnico a crear un informe del proyecto adecuado. Es importante hacerlo antes de crear tu propia evaluación del trabajo del escritor técnico.
Verifica lo siguiente:
- El envío debe cumplir con los requisitos descritos anteriormente.
- La entrega debe incluir una descripción del trabajo realizado, los requisitos cumplidos y los motivos de las decisiones específicas que se tomaron.
La idea de Season of Docs no es que los escritores técnicos produzcan una gran cantidad de documentación. Es importante que el trabajo sea potencialmente útil para el proyecto de código abierto de hosting.