Proyecto DIPY

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:

MORADO

Escritor técnico:

Areesha 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 escritura técnica. Tengo más de 4 años de experiencia en la creación de documentación de software de alta calidad, guías de usuario, manuales y descripciones de proyectos. Vivo en Islamabad, Pakistán (zona horaria: UTC + 5). Actualmente trabajo como pasante en Solidario, que continuará hasta el 18 de agosto. Participé en Google Season of Docs como escritora técnica de 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 usuarios finales completa y actualizada en inglés. Me seleccionaron en Solidario en la organización Perl & Raku para la ronda de mayo a agosto de 2020 como desarrollador de backend del servidor de Open Food Facts. Además del desarrollo de back-end, una de las tareas más importantes de esta pasantía es crear la documentación de 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 código abierto y luego participé en la temporada de Documentos de Google. Este año, fui seleccionado en Solidario, que apoya la diversidad en el código abierto y el software gratuito. Tengo un gran control sobre Git, ya que mi proyecto de Solidario se aloja en GitHub y desde marzo hago contribuciones periódicas a Open Food Facts y Mozilla Fenix. Soy usuario de Linux desde hace más de 3 años y uso comandos de terminal desde entonces.

Las herramientas de documentación y los lenguajes que he usado son Sphinx, Read the docs 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. Esto me ayudará a entender mejor las neuroimágenes y me ayudará a crear documentación. Tengo amplia experiencia en el campo de la medicina. Desarrollé un sitio web médico para médicos, pacientes, laboratorios y conductores de ambulancia. Trabajé en otro sistema utilizado por médicos, pacientes, enfermeras, investigadores y asistentes de laboratorio. Esto me ayudará a crear documentación que el público pueda comprender más fácilmente.

Revisé la documentación de DIPY y noté varias fallas en la documentación. 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. Puede ser tedioso y requerir mucho tiempo, especialmente 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 resultó difícil acceder a la guía del usuario y a la guía para desarrolladores. La documentación debe modificarse de forma tal que la información requerida por el usuario sea de fácil acceso. La documentación carece de coherencia.

Planeo hacer lo siguiente:

Define una estructura y una plantilla específicas para la documentación. Cambia la forma de la documentación de modo que los usuarios puedan navegar fácilmente y encuentren la información requerida. Produce una hoja de ruta o lista de elementos de trabajo para involucrar a la comunidad en tareas de documentación adicionales. Define plantillas para la guía del usuario y la guía para desarrolladores. Define plantillas para contribuir con 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 nuevos usuarios para que contribuyan al proyecto) Agrega la interfaz de comandos no textuales a la documentación del proyecto.

Guía del usuario:

Para la guía del usuario, me centraría en usar un lenguaje simple y claro 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 privilegiada que un usuario nuevo pueda no conocer. También me centraré en usar contenido visual, como imágenes, capturas de pantalla con anotaciones, gráficos y videos, que le muestren rápidamente al usuario cómo funciona el sistema. Una buena documentación necesita una jerarquía de encabezados y subtítulos que 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 era crear contenido accesible. Todos los documentos y guías seguirían un estilo coherente. Es indispensable usar fuentes coherentes y colores complementarios en varios documentos. Me aseguraré de que los usuarios tengan acceso a más recursos de la organización sobre cómo 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 crear contribuciones al código fuente de DIPY. Intenta presentar las diversas opciones disponibles para que puedas usar el enfoque correcto, dependiendo de lo que quieras lograr. La guía de desarrollo debe modificarse y estructurarse. Reescribiré el contenido de la guía para desarrolladores. Se incluirán fácilmente 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, y los desarrolladores podrán acceder a ellos con facilidad. Cuando los nuevos colaboradores se apresuran a ingresar a tu proyecto para hacer su primera contribución con código abierto, confían en las pautas de contribución 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. Contribuir con el proyecto debe ser lo más fácil y transparente posible para los usuarios, ya sea: Enviar una corrección Informar un error 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. Se puede modificar y agregar o quitar secciones según los requisitos del documento.

Contribución a DIPY

• Nota de bienvenida

TOC

Código de conducta

• Nuestros estándares
• Ejemplos de comportamiento que contribuyen a crear un entorno positivo
• Ejemplos de comportamiento inaceptable 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 lista de lenguajes de programación, frameworks o herramientas que se usan en tu proyecto]. Si aún no te sientes preparado para contribuir con el código, no hay problema. También puedes consultar los problemas de documentación [vínculo a la etiqueta o la etiqueta de los documentos en la Herramienta de seguimiento de errores] o los problemas de diseño que tenemos [vínculo a la etiqueta de diseño o la etiqueta en la Herramienta de seguimiento de errores si tu proyecto hace 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 puedan 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 deben instalarse. Ejecuta el comando install project para 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 relacionados con la solicitud de ayuda #### Solicitud de extracción
• Proceso de creación de la solicitud de extracción
• Verifica que todas las verificaciones de estado estén aprobadas.

¿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, ubicada en [e-mail], en el chat del IRC o [mencionar cualquier otra plataforma de comunicación que use tu proyecto].

Licencia

En esta sección, se informará sobre la licencia del proyecto.

Compromiso de tiempo y comunicación:

Te daré 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 vinculación comunitaria, analizaré los medios de comunicación y finalizaré las reuniones semanales, los medios y el tiempo para esas reuniones con mi mentor. Mantendré a mi mentor al tanto de mi trabajo y le enviaré los detalles de mi trabajo por correo electrónico. Prefiero usar TeamViewer para comunicarme, ya que es fácil de usar con muchas funciones como pantalla compartida, etcétera.