Proyecto DIPY

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

Resumen del proyecto

Organización de código abierto:

DIPY

Redactor 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 redacción técnica. Tengo más de 4 años de experiencia en la redacción de documentación de software, guías de usuario, manuales y descripciones de proyectos de alta calidad. Vivo en Islamabad, Pakistán (Zona horaria: UTC + 5). Actualmente, trabajo como pasante en Outreachy, que continuará hasta el 18 de agosto. Participé en Google Season of Docs como escritora técnica en la organización OpenELIS Global. La documentación original estaba en francés, era limitada y desactualizada, por lo que creé una documentación para el usuario final extensa y actualizada en inglés. Fui seleccionado en Outreachy 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 backend, una de las tareas principales de esta pasantía es crear documentación para módulos y funciones en formato POD. Ingresé al mundo del código abierto el año pasado cuando contribuí en algunos proyectos de código abierto y, más tarde, participé en la Temporada de Documentos de Google. Y este año, me seleccionaron en Outreachy, que apoya la diversidad en el software libre y de código abierto. Tengo un buen manejo de Git, ya que mi proyecto de Outreachy está alojado en GitHub y he estado haciendo contribuciones periódicas a Open Food Facts y Mozilla Fenix desde marzo. Soy usuario de Linux desde hace más de 3 años y uso comandos de terminal desde entonces.

Las herramientas y los lenguajes de documentación que usé 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. Me ayudará a comprender mejor la neuroimagen y a crear documentación. Tengo una amplia experiencia en el campo de la medicina. Desarrollé un sitio web para médicos, pacientes, laboratorios y conductores de ambulancias. Trabajé en otro sistema que usan médicos, pacientes, enfermeras, asistentes de laboratorio y, también, investigadores. Esto me ayudará a crear documentación que será más fácil de entender para el público.

Revisé la documentación de DIPY y anoté varias fallas en ella. Hay varios vacíos en la documentación que planeo mejorar. Estado actual de la documentación: La documentación carece de una estructura y un diseño específicos. La navegación puede ser tediosa y llevar mucho tiempo, en especial para los usuarios nuevos. Los usuarios pueden tener dificultades para 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 manera que se pueda acceder fácilmente a la información que necesita el usuario. La documentación carece de coherencia.

Mi plan es hacer lo siguiente:

Definir una estructura y una plantilla específicas para la documentación Cambiar la forma de la documentación, de modo que los usuarios puedan navegar fácilmente y encontrar la información requerida Producir una hoja de ruta o una lista de elementos de trabajo para que la comunidad participe 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 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 (lo que puede ayudar y motivar a nuevos usuarios para que contribuyan a la documentación con coherencia en el proyecto) Agrega explicaciones no textuales de la interfaz para mejorar la documentación de la interfaz de comandos

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. Se evitaría el uso de jerga, acrónimos y otra información privilegiada que un usuario nuevo podría no conocer para brindar una mejor experiencia del usuario. También me centraré en usar contenido visual, como imágenes, capturas de pantalla con anotaciones, gráficos y videos, que les muestren rápidamente al usuario cómo funciona el sistema. Una buena documentación necesita una jerarquía de encabezados y subtítulos que le permitan 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 las guías tendrán un estilo uniforme. Es fundamental 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 orientación y materiales de referencia para ayudar al desarrollador a realizar contribuciones al código fuente de DIPY. Intenta explicar las diferentes opciones disponibles para que puedas usar el enfoque correcto, según lo que quieras lograr. La guía de desarrollo debe modificarse 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 contribuciones, la guía de estilo, las convenciones de codificación, la guía de documentación, la instalación del entorno de desarrollo, la depuración, la guía de pruebas y el contenido relacionado, y los desarrolladores podrán acceder a ellos fácilmente. Cuando los nuevos colaboradores ansiosos se dirigen a tu proyecto para hacer su primera contribución de código abierto, confían en los lineamientos para contribuir como su guía. De esta manera, los lineamientos serían fáciles de leer, detallados y amigables. Las guías de contribución son documentos útiles que indican cómo las personas pueden contribuir al proyecto de código abierto. Contribuir al 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 se pueden agregar o quitar secciones según los requisitos del documento.

Cómo contribuir a DIPY

• Nota de bienvenida

TOC

Código de conducta

• Nuestros estándares
• Ejemplos de comportamientos que contribuyen a crear un entorno positivo
• Ejemplos de comportamientos inaceptables de los participantes
• Nuestras responsabilidades
• Responsabilidades de los mantenedores de proyectos
• Alcance

Alcance del Código de Conducta

¿Qué necesito saber para ayudarte?

Si quieres ayudar con una contribución de código, nuestro proyecto usa [insertar lista de lenguajes de programación, frameworks o herramientas que usa tu proyecto]. Si aún no te sientes en condiciones de hacer una contribución de código, no hay problema. También puedes consultar los problemas de documentación [vínculo a la etiqueta de documentación en tu herramienta de seguimiento de errores] o los problemas de diseño que tenemos [vínculo a la etiqueta de diseño en la herramienta de seguimiento de errores si tu proyecto realiza un seguimiento de los problemas de diseño]. Si te interesa contribuir con código y te gustaría obtener más información sobre las tecnologías que usamos, consulta la lista a continuación. Incluye una lista con viñetas de recursos (instructivos, videos y libros) que los colaboradores nuevos puedan usar para saber qué deben saber los usuarios 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 install project para instalar $project.

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

Cómo colaborar

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 solicitudes 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 (buena) sugerencia de mejoras?

Tu primera contribución de código

• Problemas para principiantes
• Problemas de ayuda #### Solicitud de extracción
• Proceso para crear una solicitud de extracción
• Verifica que todas las verificaciones de estado se aprueben.

¿Qué sucede si fallan las verificaciones de estado?

• Pruebas de escritura
• Cobertura de las pruebas

Guías de estilo

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

Asistencia

Si tienes algún problema, 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 en [menciona 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:

Trabajaré más de 45 horas a la semana, pero en caso de que haya algún inconveniente, compensaré esas horas los fines de semana. Durante el período de vinculación con la comunidad, hablaré sobre los medios de comunicación y definiré las reuniones semanales, los medios y la hora de esas reuniones con mi mentor. Mantendré a mi mentor al tanto de mi trabajo y le enviaré los detalles por correo electrónico. Prefiero usar TeamViewer para la comunicación, ya que es fácil de usar con muchas funciones, como compartir pantallas, etcétera.