En esta página, se incluyen 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 para la biología de redes (NRNB)
- Redactor técnico:
- Prubhtej_9
- Nombre del proyecto:
- Crear documentación para el usuario de SynBioHub y desarrollar instructivos para casos de uso específicos
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Resumen
La documentación para el usuario está diseñada para ayudar a los usuarios finales a usar un producto o servicio. Una buena documentación para el usuario es muy importante porque les brinda a los usuarios una forma de aprender a usar un software, sus funciones, sugerencias y trucos, y también resolver problemas comunes que se encuentran cuando se usa el software. 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 un signo de un producto y un equipo de desarrolladores saludables. Sin una buena documentación para el usuario, es posible que este no sepa cómo hacer las acciones mencionadas anteriormente de manera eficaz y eficiente. La documentación para el usuario puede desempeñar un papel fundamental para garantizar el éxito de un producto, ya que una buena comunicación es y siempre será el centro de cualquier empresa o producto, y una buena documentación solo toma esa comunicación y la coloca en un marco de trabajo manejable al que todos pueden acceder para tener éxito. SynBioHub es un repositorio de diseño para la biología sintética. Está disponible como sitio web público y 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 diseños y partes sintéticas como servicio, compartir diseños con colaboradores y almacenar diseños de sistemas biológicos de forma local. Se puede acceder a los datos de SynBioHub a través de la API de HTTP, la API de Java o la API de Python, y luego se pueden integrar en herramientas de CAD para crear diseños genéticos.
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, que puede ayudar al usuario a navegar dentro del repositorio de diseño. Además, la documentación de la API necesita un poco de actualización, con algunos temas específicos, como la solución de ciertos problemas peculiares que puede enfrentar un usuario. Si bien la organización grabó algunos videos instructivos, como el que se muestra aquí. No hay documentación escrita para el usuario sobre SynBioHub que pueda guiarlo.
¿Por qué la documentación de usuario propuesta es una mejora con respecto a la actual? Compilaré la documentación de la GUI desde cero con GitHub y Markdown, como sugirió el mentor, el Sr. Chris Myers. La documentación del usuario propuesta se estructurará para mejorar y garantizar la eficiencia, la coherencia y la tranquilidad de cualquier usuario final. Contendrá guías escritas y sus imágenes asociadas, así como 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 unirá a la GUI y contendrá 6 secciones, de las cuales la 6ª será opcional. Las secciones se mencionan de la siguiente manera: 1. Introducción 2. Instrucciones de instalación a) Desde una imagen precompilada b) Desde la fuente c) Configuración de NGINX 3. Instrucciones para el usuario: a) Instrucciones detalladas para usar cada función de la GUI b) Instructivos para casos de uso comunes 4. Documentación de la API: sección 5 de Endpoints Documentación del complemento 6. Solución de problemas y referencias futuras.
Parte 1:
En esta sección, se les proporcionará a los usuarios una introducción detallada y varios instructivos sobre SynBioHub.
Parte 2:
En esta sección, se describen las diferentes formas en que el usuario puede instalar el software de código abierto con varios métodos, a saber: a) Desde una imagen precompilada b) Desde la fuente c) Configuración de NGINX
Parte 3:
Esta es la parte más crucial de la documentación y ocupará la mayor parte del tiempo. Aquí, se agregará cada detalle en contexto a la GUI. Como se mencionó anteriormente, en esta sección se abordarán principalmente dos inquietudes, es decir, instrucciones detalladas para 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. Extremos del usuario 2. Buscar en Endpoints 3. Extremos de descarga 4. Descarga los extremos 5. Extremos del envío 6. Extremos de permisos 7. Edita los extremos. 8. Extremos de archivos adjuntos 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: especificación y, luego, implementación del complemento. 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 solucionar problemas. Según el debate con el señor Myers, se ha decidido que esta sección se puede fusionar con la sección de introducción en caso de que no se prolongue demasiado. Análisis El Sr. Myers y yo conversamos sobre cómo actualizar la documentación existente y también 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 estimado en la página 5 a continuación. Según la discusión, usaré GitHub y Markdown para compilar la documentación de cada sección, excepto la parte 4, en la que se usará Slate. 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 de aspecto a partir de un conjunto de archivos markdown. El desarrollador Robert Lord lo creó 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 hacer de código abierto el proyecto y el resto es historia. Tiene las siguientes características: • Diseño intuitivo y sencillo: Con Slate, la descripción de tu API se encuentra en el lado izquierdo de la documentación, y todos los ejemplos de código se encuentran en el lado derecho. Se inspira en los documentos de la API de Stripe y PayPal. Slate es responsiva, por lo que se ve genial en tablets, teléfonos e incluso en medios impresos. • Todo en una sola página: Atrás quedaron los días en que tus usuarios tenían que buscar en 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 desplazas, el hash de tu navegador se actualizará al encabezado más cercano, por lo que vincular a un punto en particular de la documentación sigue siendo natural y fácil. • Slate es solo Markdown: Cuando escribes documentos con Slate, solo escribes Markdown, lo que facilita su edición y comprensión. Todo está escrito en Markdown, incluso las muestras de código son solo bloques de código Markdown. • Escribe muestras de código en varios lenguajes: Si tu API tiene vinculaciones en varios lenguajes de programación, puedes colocar fácilmente pestañas para alternar entre ellos. En tu documento, distinguirás diferentes idiomas especificando el nombre del idioma en la parte superior de cada bloque de código, al igual que con GitHub Flavored Markdown. • Destacado de sintaxis listo para usar en más de 100 idiomas, sin necesidad de configuración • Índice automático que se desplaza con fluidez en el extremo izquierdo de la página. A medida que te desplazas, se muestra tu posición actual en el documento. También es rápido. En TripIt, usamos Slate para crear documentación para nuestra nueva API, cuyo índice tiene más de 180 entradas. Nos aseguramos de que el rendimiento siga siendo excelente, incluso para 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 en las páginas de GitHub, sino que también facilita que otros desarrolladores hagan solicitudes de extracción a tus documentos si encuentran errores tipográficos u otros problemas. Por supuesto, si no quieres usar GitHub, también puedes alojar tus documentos en otro lugar. • Compatibilidad con RTL diseño completo de derecha a izquierda para idiomas RTL como el árabe, el persa (Farsi), el hebreo y otros En las siguientes secciones, se analiza una vista más detallada de la documentación. Estructura de la documentación propuesta: creé una estructura para la guía del usuario de SynBioHub que se encuentra en la página 2. El Sr. Myers aceptó esta estructura y ya la modificó . Objetivos del proyecto 1. Reestructura la documentación. 2. Se actualizó la documentación para que se ajuste a las versiones modernas de SynBioHub. 3. Quita la información obsoleta. 4. Vuelve a escribir la documentación del usuario para que sea más fácil de entender. 5. Incluye una breve sección de requisitos previos en la documentación para los colaboradores nuevos para aumentar su comprensión básica de los conceptos biológicos básicos y la interfaz de SynBioHub.