Proyecto DIPY

Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.

Resumen del proyecto

Organización de código abierto:

DIPO

Redactor técnico:

Aresha Tariq

Nombre del proyecto:

Reestructuración de alto nivel y enfoque en el usuario final

Duración del proyecto:

Duración estándar (3 meses)

Project description

Soy ingeniero de software y tengo experiencia en redacción técnica. Tengo más de 4 años de experiencia en la creación de documentación, guías de usuario, manuales y descripciones de proyectos de software de alta calidad. Vivo en Islamabad, Pakistán (zona horaria: UTC + 5). Trabajo como pasante en Solidaridad y trabajo hasta el 18 de agosto. Participé en Google Season of Docs como escritor técnico en la organización OpenELIS Global. La documentación original estaba en francés, era limitada y estaba desactualizada, por lo que creé una documentación para el usuario final en inglés amplia y actualizada. Me eligieron como desarrollador de backend del servidor Open Food Facts durante la ronda de mayo a agosto de 2020 en el programa Solidario de la organización Perl & Raku. Además del desarrollo de back-end, una de las tareas principales de esta pasantía es crear documentación para los módulos y funciones en formato POD. El año pasado ingresé al mundo del código abierto cuando contribuí en algunos proyectos de ese tipo y, luego, participé en Google Season of Docs. Este año, me seleccionaron en Solidaridad, que apoya la diversidad en el ámbito de software libre y de código abierto. Tengo un gran control sobre Git, ya que mi proyecto de Solidario se aloja en GitHub y he realizado contribuciones periódicas a Open Food Facts y Mozilla Fenix desde marzo. Soy usuario de Linux durante los últimos 3 años y uso comandos de terminal desde entonces.

Las herramientas de documentación y los lenguajes que he usado son Sphinx, Leer los documentos y Markdown. Me gustó esta idea y quiero trabajar en ella porque tengo experiencia relevante y me encantaría usar mis conocimientos y habilidades para contribuir a DIPY. Tengo experiencia en el campo del procesamiento de imágenes digitales, la visión artificial y el aprendizaje automático. Me ayudará a comprender mejor las neuroimágenes y me ayudará a crear documentación. Cuento con mucha experiencia en el campo de la medicina. Desarrollé un sitio web médico para médicos, pacientes, laboratorios y conductores de ambulancias. Trabajé en otro sistema que usan médicos, pacientes, enfermeras, asistentes de laboratorio e investigadores. Esto me ayudará a crear documentación que el público podrá entender más fácilmente.

Revisé la documentación de DIPY y anoté varias fallas en ella. Hay varias brechas en la documentación que pienso mejorar. Estado actual de la documentación: La documentación carece de una estructura y un diseño específicos. La navegación de los usuarios nuevos puede ser tedioso y lento, en especial para los usuarios nuevos. A los usuarios les resulta difícil obtener información de la guía. Se debe mejorar el contenido de la documentación. Como usuario nuevo, me resulta difícil acceder a la guía del usuario y a la guía para desarrolladores. La documentación debe modificarse de manera tal que la información que requiere el usuario sea de fácil acceso. La documentación no es coherente.

Planeo hacer lo siguiente:

Define una estructura y plantilla específicas para la documentación. Modifica la documentación de modo que los usuarios puedan navegar y encontrar la información necesaria. Crea una hoja de ruta o una lista de elementos de trabajo para involucrar a la comunidad en más trabajos de documentación. Define plantillas para la guía del usuario y la guía para desarrolladores. Define plantillas para contribuir a la guía. Reescribe, reestructura y actualiza la guía del usuario, la guía de desarrollo y la guía de contribución (que puede ayudar y motivar a los usuarios nuevos para que contribuyan al proyecto)

Guía del usuario:

Para la guía del usuario, me centraría en usar un lenguaje simple y simple para ayudar a los usuarios a comprender incluso los sistemas más complejos. Para mejorar la experiencia del usuario, se evitarían la jerga, los acrónimos y otra información interna que quizás el usuario nuevo no conozca. También me centraré en usar contenido visual, como imágenes, capturas de pantalla con anotaciones, gráficos y videos, que le muestre rápidamente al usuario cómo funciona el sistema. Una buena documentación necesita una jerarquía de encabezados y subtítulos que le permita al usuario saber qué le mostrará cada sección. Y esa jerarquía debe seguir un flujo lógico que ayude al usuario a aprender a usar el sistema de la manera más útil. Uno de los objetivos principales de este proyecto sería crear contenido accesible. Todos los documentos y guías seguirían un estilo coherente. Usar fuentes coherentes y colores complementarios en múltiples documentos es imprescindible. Me aseguraré de que los usuarios tengan acceso a más recursos de la organización para que puedan tener éxito con el sistema.

Guía para desarrolladores:

La guía para desarrolladores incluye una amplia guía y materiales de referencia para ayudar al desarrollador a realizar contribuciones al código fuente de DIPY. Intenta presentar las distintas opciones disponibles para que puedas usar el enfoque correcto en función de lo que quieras lograr. La guía de desarrollo debe reestructurarse y reestructurarse. Volveré a escribir el contenido de la guía para desarrolladores. Se incluirán las dependencias de compilación, la guía de contribución, la guía de estilo, las convenciones de programación, la guía de documentación, la instalación del entorno de desarrollo, la depuración, la guía de pruebas y otros elementos relacionados, que además se facilitarán a los desarrolladores. Cuando los ansiosos nuevos colaboradores se apresuran a hacer su primera contribución con código abierto, confían en los lineamientos para las contribuciones como guía. Por lo tanto, las pautas serían fáciles de leer, detalladas y amigables. Las guías de contribución son documentos útiles que comunican cómo las personas pueden contribuir al proyecto de código abierto. Hacer una contribución al proyecto debe ser lo más fácil y transparente posible para los usuarios, ya sea que se trate de: Enviar una corrección Informar un error Cómo convertirse en encargado de mantenimiento Analizar el estado actual del código Proponer nuevas funciones

TEMPLATE

Esta es una de las plantillas que se pueden usar para la guía de contribución. Puedes modificarla y agregar o quitar secciones según los requisitos del documento.

Contribución a DIPY

• Nota de bienvenida

TCO

Código de conducta

• Nuestros estándares
• Ejemplos de comportamiento que contribuye a crear un entorno positivo
• Ejemplos de comportamiento inaceptable por parte de los participantes
• Nuestras responsabilidades
• Responsabilidades de los encargados de mantener el proyecto
• Permiso

Alcance del Código de Conducta

¿Qué necesito saber para ayudar?

Si buscas ayudar con una contribución de código, nuestro proyecto utiliza [insertar la lista de lenguajes de programación, frameworks o herramientas que usa tu proyecto]. Si aún no quieres hacer una contribución de código, no hay problema. También puedes consultar los problemas de documentación [vínculo a la etiqueta o etiqueta de los documentos en tu Herramienta de seguimiento de errores] o los problemas de diseño que tenemos [vínculo a etiqueta de diseño o etiqueta del seguimiento de problemas si tu proyecto realiza un seguimiento de los problemas de diseño]. Si te interesa hacer una contribución de código y quieres obtener más información sobre las tecnologías que usamos, consulta la lista que aparece a continuación. Incluye una lista con viñetas de recursos (instructivos, videos, libros) que los nuevos colaboradores pueden usar para aprender lo que los usuarios necesitan saber para contribuir al proyecto.

Cómo configurar el entorno de desarrollo

En esta sección, agregaré el procedimiento de instalación y las dependencias que se deben instalar. Ejecuta el comando para instalar $project si quieres instalar $project

• Código fuente: github.com/$project/$project
• Herramienta de seguimiento de errores: github.com/$project/$project/issues

Cómo contribuir

Cómo informar un error

• Antes de enviar un informe de errores
• ¿Cómo envío un informe de errores (bueno)?

Cómo enviar cambios

• Protocolos de solicitud de extracción
• Respuesta del equipo
• Velocidad de respuesta

Cómo solicitar una mejora

• Antes de enviar una sugerencia de mejora
• ¿Cómo envío una sugerencia de mejora (buena)?

Tu primera contribución de código

• Problemas para principiantes
• Problemas que se necesitan #### Solicitud de extracción
• Proceso de creación de la solicitud de extracción
• Verifica que se aprueben todas las verificaciones de estado.

¿Qué sucede si fallan las verificaciones de estado?

• Escribe pruebas
• Cobertura de pruebas

Guías de estilo

• Mensajes de confirmación de Git
• Estilo estándar

Asistencia

Si tienes problemas, comunícate con nosotros. Si necesitas ayuda, puedes hacer preguntas en nuestra lista de distribución, que se encuentra en [e-mail], en el chat de IRC o [menciona cualquier otra plataforma de comunicación que use tu proyecto].

Licencia

En esta sección, se explica la licencia del proyecto.

Compromiso de tiempo y comunicación:

Voy a dedicar más de 45 horas a la semana, pero en caso de cualquier contratiempo, compensaré esas horas los fines de semana. Durante el período de vínculo comunitario, analizaré los medios de comunicación y finalizaré las reuniones semanales, los medios y el tiempo para esas reuniones con mi mentor. Mantendré al tanto de mi trabajo a mi mentor y le enviaré los detalles de mi trabajo por correo electrónico. Prefiero usar TeamViewer para la comunicación, ya que es fácil de usar con muchas funciones, como pantallas para compartir, etc.