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:
- Recurso Nacional de Biología de Redes (NRNB)
- Escritor técnico:
- Prubhtej_9
- Nombre del proyecto:
- Crear documentación del usuario para SynBioHub y desarrollar instructivos para casos de uso específicos
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Se puede abstraer
La documentación para los usuarios está diseñada para ayudar a los usuarios finales a utilizar un producto o servicio. Una buena documentación para el usuario es muy importante porque proporciona un camino para que los usuarios aprendan a utilizar un software, sus funciones, consejos y trucos, además de resolver problemas comunes que encuentran cuando lo utilizan. También reduce el costo de asistencia y forma parte de la identidad corporativa del producto, es decir, una buena documentación para el usuario es una señal de un producto y del equipo de desarrolladores en buen estado. Sin una buena documentación del usuario, es posible que un usuario no sepa cómo hacer las cosas que se mencionaron anteriormente de manera efectiva y eficiente. La documentación del usuario puede desempeñar un papel fundamental para garantizar el éxito de un producto porque una buena comunicación es y será siempre el centro de cualquier negocio o producto, y una gran documentación solo toma esa comunicación y la coloca en un marco manejable al que todos pueden acceder para tener éxito. SynBioHub es un repositorio de diseño para biología sintética. Está disponible como sitio web público y como software de código abierto. SynBioHub usa el lenguaje abierto de biología sintética (SBOL), un estándar de código abierto para representar diseños genéticos, y también permite compartir partes de diseño de archivos GenBank y FASTA. SynBioHub se puede usar para publicar una biblioteca de piezas sintéticas y diseños como servicio, para compartir diseños con colaboradores y para almacenar diseños de sistemas biológicos a nivel local. Se puede acceder a los datos en SynBioHub a través de la API de HTTP, la API de Java o la API de Python, donde luego se pueden integrar en herramientas de CAD para crear diseños genéticos. SynBioHub tiene una interfaz para que los usuarios suban datos biológicos nuevos a la base de datos, visualicen partes de ADN, realicen consultas para acceder a las partes deseadas y descarguen la documentación de SBOL, GenBank, FASTA, etc. También hay varios documentos de investigación y algunos instructivos disponibles en Internet, como los siguientes: 1. https://pubs.acs.org/doi/abs/10.10acbiosacbios.
Estado actual de la documentación:
Actualmente, la documentación para el usuario está disponible en “https://synbiohub.github.io/api-docs/#about-synbiohub”. Esta es solo la documentación de la API y no existe la documentación de la GUI, lo que puede ayudar al usuario a navegar por el repositorio de diseño. Además, la documentación de la API requiere un poco de actualización, con algunos temas específicos, como la solución de ciertos problemas peculiares que puede enfrentar un usuario. La organización ha grabado algunos videos instructivos, como el que se muestra aquí. No hay documentación escrita para el usuario sobre SynBioHub que pueda guiar al usuario.
¿Por qué la documentación de usuario propuesta es una mejora con respecto a la actual? Desarrollaré la documentación de la GUI desde cero con GitHub y Markdown según lo que sugiera el mentor Chris Myers. La documentación del usuario propuesta se estructurará para mejorar y garantizar la eficiencia, coherencia y tranquilidad para cualquier usuario final. Contiene guías escritas y sus imágenes asociadas, e incluye instrucciones y explicaciones sobre cómo usar cada función del simulador de código abierto SynBioHub. Durante las conversaciones con el Sr. Myers, también se decidió que la documentación de la API se combinará con la GUI y contendrá 6 secciones, de las cuales la sexta será opcional. Las secciones se mencionan de la siguiente manera: 1. Introducción 2. Instrucciones de instalación a) A partir de la imagen compilada con anterioridad b) Desde el origen c) Configuración de NGINX 3 Instrucciones para el usuario a) Instrucciones detalladas sobre el uso de cada función de la GUI b) Instructivos para casos de uso comunes 4. Documentación de la API: Extremos sección 5. Documentación del complemento 6. Solución de problemas y referencias futuras
Parte 1:
En esta sección, los usuarios recibirán una introducción detallada y varios instructivos relacionados con SynBioHub.
Parte 2:
En esta sección, se detallan las distintas maneras en las que el usuario puede instalar el software de código abierto a través de varios métodos, entre ellas: a) A partir de una imagen ya compilada b) Desde la fuente c) La configuración de NGINX
Parte 3:
Esta es la parte más importante de la documentación y ocupará la mayor parte del tiempo. En este documento, se agregarán cada detalle en contexto a la GUI. Como se mencionó anteriormente, se abordarán principalmente dos inquietudes, p.ej., instrucciones detalladas sobre cómo usar cada función de la GUI y algunos instructivos para casos de uso comunes.
Parte-4:
Como se mencionó anteriormente, se usará slate para generar la documentación de esta parte. En esta sección, se incluirán los siguientes extremos: 1. Usuarios extremos 2. Buscar extremos 3. Descarga Endpoints. 4. Descarga Endpoints. 5. Extremos de envío 6. Extremos de permisos 7. Edita extremos. 8. Adjunto de extremos 9. Extremos de administración
Parte 5:
En esta sección, se incluirá la documentación del complemento, que ya está presente en la documentación anterior de SynBioHub. Esta sección se subdividirá en dos secciones, a saber: implementación y especificación de complementos. Parte 6: [Opcional] Esta sección incluirá una lista muy común de errores que enfrentan los usuarios y también incluirá algunas instrucciones para la solución de problemas. Según lo que analizamos en la conversación con el Sr. Myers, se decidió que esta sección se puede combinar con la introducción en caso de que el tiempo no sea muy extenso. Análisis El Sr. Myers y yo tuvimos una conversación sobre cómo actualizar la documentación existente y cómo escribir una nueva para la GUI . En esas pocas conversaciones, formulamos un diseño básico para la nueva documentación que se mencionó anteriormente y se proporcionó un cronograma de estimación en la página 5 a continuación. Según lo que explicamos, usaré GitHub y Markdown para crear la documentación de cada sección, excepto la parte 4 de la documentación en la que se usará una cortinilla de video. Slate:- Slate te ayuda a crear documentación de API atractiva, inteligente y responsiva. Slate es una herramienta basada en Ruby que genera un sitio estático de documentación de la API con tres paneles y un excelente aspecto a partir de un conjunto de archivos de Markdown. Fue construido por Robert Lord en 2013, cuando era pasante de 18 años en la empresa de software de viajes "Tripit". Convenció a su jefe en ese momento para que le permitiera configurar el proyecto con código abierto, y el resto es historia. Tiene las siguientes características: • Diseño intuitivo y limpio: Con Slate, la descripción de tu API aparece en el lado izquierdo de tu documentación y todos los ejemplos de código están en el lado derecho. Está inspirado en los documentos de la API de Stripe y PayPal. Slate es adaptable, por lo que se ve muy bien en tablets, teléfonos y hasta en impresiones. • Todo en una sola página: Atrás quedaron los días en que los usuarios tenían que hacer una búsqueda entre un millón de páginas para encontrar lo que querían. Slate coloca toda la documentación en una sola página. Sin embargo, no sacrificamos la vinculación. A medida que te desplaces, el hash de tu navegador se actualizará al encabezado más cercano, por lo que vincular a un punto específico de la documentación sigue siendo natural y fácil. • Slate es solo Markdown: cuando escribes documentos con Slate, solo escribes Markdown, por lo que es fácil de editar y entender. Todo se escribe en Markdown, incluso los ejemplos de código son solo bloques de código de Markdown. • Escribe muestras de código en varios lenguajes: Si tu API tiene vinculaciones en varios lenguajes de programación, puedes ubicar pestañas fácilmente para alternar entre ellos. En tu documento, podrás distinguir diferentes lenguajes si especificas el nombre del idioma en la parte superior de cada bloque de código, al igual que con GitHub Flavored Markdown. • Opción de resaltado de sintaxis lista para usar en más de 100 idiomas, sin necesidad de configuración. • Índice automático que se desplaza sin problemas en el extremo izquierdo de la página. A medida que te desplaces, se mostrará tu posición actual en el documento. También es rápido. Estamos utilizando Slate en TripIt para compilar documentación para nuestra nueva API, donde nuestro índice tiene más de 180 entradas. Nos aseguramos de que el rendimiento siga siendo excelente, incluso para los documentos más grandes. • Permite que los usuarios actualicen la documentación por ti: De forma predeterminada, la documentación generada por Slate se aloja en un repositorio público de GitHub. Esto no solo significa que obtendrás hosting gratuito para tus documentos con las páginas de GitHub, sino que también facilita que otros desarrolladores realicen solicitudes de extracción a tus documentos si encuentran errores tipográficos u otros problemas. Si no quieres usar GitHub, también puedes alojar tus documentos en otro lugar. • Compatibilidad con RTL con diseño completo de derecha a izquierda para idiomas con escritura de derecha a izquierda, como el árabe, el persa (Farsi) y el hebreo, entre otros. Veredicto Slate es uno de los software de código abierto más potentes para generar la documentación y, según las conversaciones que mantuve con mi mentor, el Sr. Chris Myers, usaré Slate para la Parte 4 y, para otras partes, se usará GitHub y Markdown. En las siguientes secciones, se proporciona una vista más detallada de la documentación. Estructura de la documentación propuesta que creé una estructura para la guía del usuario de SynBioHub, que se encuentra en la página 2 Esta estructura se aceptó y ya fue modificada por el Sr. Myers . Objetivos del proyecto 1. Reestructura la documentación. 2. Actualiza la documentación para adaptarla a las versiones modernas de SynBioHub. 3. Quita la información obsoleta. 4. Reescribe la documentación del usuario para que sea más fácil de entender. 5. Incluye una sección breve de requisitos previos en la documentación para nuevos colaboradores para que puedan comprender mejor los conceptos biológicos básicos y la interfaz de SynBioHub.