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:
- Creative Commons
- Redactor técnico:
- nimishnb
- Nombre del proyecto:
- Guía de uso de vocabulario
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Sinopsis del proyecto
Vocabulary tiene un gran potencial para usarse como una biblioteca principal de componentes de IU para la creación de sitios web. Lo que necesita es una guía práctica sólida pero fácil de usar. La información importante para desarrolladores, como las guías de componentes, las especificaciones de uso y los ajustes de configuración, forman una parte esencial de cualquier documentación. Esto no solo animará a los usuarios existentes a tener una idea de cómo el vocabulario continúa creciendo y alcanzará nuevos hitos, sino que también promoverá el uso de vocabulario en proyectos comparativamente más nuevos. Los resultados deseados de mi trabajo como pasante no solo implicarían redactar una guía práctica para usar los componentes preexistentes, sino también diseñar y desarrollar una página de inicio (lo que da como resultado una documentación integrada para cada uno) de vocabulario, vocabulario y fuentes.
Planificación del proyecto
El problema: La documentación es una de las principales razones que determinan el éxito de una biblioteca de código abierto determinada. La principal pregunta que piensan los desarrolladores cuando eligen una pila tecnológica adecuada para compilar sus aplicaciones es “¿La biblioteca está bien documentada? ¿Está bien mantenido? ¿Tiene una cantidad considerable de uso y soporte de errores?”. Estas son exactamente las preguntas que deberíamos hacernos mientras abordamos esta idea de proyecto. Desde la perspectiva de la ingeniería de software:
Análisis de requisitos: Es una necesidad inmanente de tener una documentación concisa y consolidada para satisfacer nuestras necesidades. La falta de documentación perjudica las perspectivas futuras de las aplicaciones de código abierto y es, por mucho, un componente esencial y no insignificante. Los vínculos a estas documentación deben incluir una página principal atractiva que capture el interés de las personas en un instante. La documentación debe estar bien organizada, lo que permita un flujo sin interrupciones.
Especificaciones: Según los requisitos, se pueden decidir las especificaciones. El contenido de la documentación se puede formar a partir de los datos presentes en los sitios web de Netlify de CC, junto con algo de inspiración de documentación conocida, como la IU semántica, scikit-learn, NumPy, Boot, etc. El resultado de esta tarea sería la página de destino requerida y las guías de documentación completas.
Estos son algunos problemas generales relacionados con el vocabulario, el vocabulario y las fuentes:
Existe una ausencia de documentación y, aunque la haya, algunas partes están dispersas por todos los sitios web de Netlify. Esto no les permite a los usuarios, desarrolladores ni colaboradores externos usar nuestra biblioteca.
Para acceder a un componente determinado y copiar el código correspondiente, se necesitan más clics. Una simple búsqueda de Google con algo como "Tabs component CC Vocabulary" no mostrará la información deseada. Una opción de búsqueda dentro de las guías de documentación mejoraría significativamente la UX.
Una descripción textual un poco más detallada de los componentes, que describe los detalles discretos.
No hay opción de publicación en vivo. Una ejecución en vivo es compatible con varios sitios, como JSFiddle, que permite a los desarrolladores tener una idea del componente sin ejecutar una aplicación completa para ver cómo funciona.
La solución
Hay varias soluciones posibles. Sin embargo, mencionaré algunos y presentaré mi solución final en la parte de conclusión:
= El uso de readthedocs readthedocs es una solución conocida para escribir documentación para bibliotecas de código abierto. Se basa en Sphinx, la herramienta de documentación de Python.
Ventajas:
- Es una forma de generación de documentación ampliamente aceptada que usan organizaciones como Ethereum (Solidity).
- Documentación con una estructura óptima.
- Hosting estático gratuito.
Desventajas:
- Falta de control absoluto sobre el estilo
= Uso de Sphinx Podríamos usar Sphinx de forma nativa para la parte de documentación, ya que proporciona buenas funciones para todos nuestros fines.
Ventajas:
- La herramienta de Python más popular para la documentación.
- También admite búsquedas de documentación.
- El CSS predeterminado se puede reemplazar por uno personalizado; se aplica cierto control sobre el código HTML mediante archivos .rst.
Desventajas:
- Implicaría programar en Python y en formato de texto reestructurado (.rst), que será una desviación de los lenguajes sugeridos para el proyecto.
= Usar temas de Jekyll Los temas Jekyll están integrados en las páginas de GitHub, y hay plantillas preexistentes que pueden personalizarse según nuestras necesidades.
Ventajas:
- Temas de documentación listos para todos los fines.
- Los estilos y CSS predeterminados se pueden anular por los personalizados, así como el control de HTML.
- Extrae el CSS Primer predeterminado para compilar las páginas.
- Integración sencilla en las páginas de GitHub
Desventajas:
- Es posible que no proporcione la mejor estructuración de documentación.
=Usar páginas de GitHub Las páginas estándar de github para compilar nuestro sitio estático (HTML, CSS, JS).
Ventajas:
- Tiene control total sobre casi todo lo que está en cuestión.
- Máxima flexibilidad para decidir el diseño, los colores y los estilos.
- Es fácil usar los componentes de Vocabulary.
- Incorporación sencilla de fragmentos de código y vínculos de ejecución en vivo.
Desventajas:
- Podría ser un enfoque que requiera más tiempo.
= Usar Haroopad Esto proporciona una solución alternativa de Markdown.
Ventajas:
- Implicaría tener un código mínimo complicado.
- El enfoque sería escribir la documentación a la perfección.
Desventajas:
- Falta de control sobre CSS.
- En ocasiones, puedes contar con el mejor apoyo de la comunidad.
- Es posible que no sea compatible con MDX.
= Usar MKDocs Esto ofrece otra solución alternativa de Markdown.
Ventajas:
- Implicaría tener un código mínimo complicado (otra vez).
- Escribe más código, menos código.
Desventajas:
- Falta de control sobre CSS.
- Es posible que no cuentes con la mejor asistencia de la comunidad.
- Utiliza Python. Puede que surja aún más la necesidad de iniciar una instancia de Amazon S3.
= Uso de VueJS +StorybookJS Este enfoque se usa comúnmente en Vocabulary y sus repositorios asociados.
Ventajas:
- Apegarse a las tecnologías que tienen la garantía de funcionar bien, dadas las experiencias laborales pasadas.
- Conocimientos de la base de código
- No existe tecnología competente en este espacio.
Desventajas:
- También pueden existir opciones más simples para los mismos fines.
Para concluir, me gustaría pensar que el enfoque que involucra el enfoque de VueJS+Storybook (HTML,CSS,JS) parece el más adecuado, dado que también estoy cómodo con él. Sin embargo, esto también significa que no nos perderemos por completo en el desarrollo de esta aplicación. También sería bastante sencillo usar los componentes de CC-Vocabulary. Sin embargo, para decidir la estructura de la documentación, debemos considerar definitivamente la forma en que se divide el contenido entre los subtítulos en la documentación de readthedocs. Me impresionó el sitio web de Semantic-UI (que utiliza StoryBook), ya que tiene un aspecto minimalista y permite saber fácilmente lo que buscan con unos pocos clics. Además de la IU semántica, también revisé Material Design, Primer, Bootstrap, Carbon Design, etc., para usarlos como guías de estilo de IU y sistemas de diseño para mi trabajo. También podemos buscar temas de documentación de Jekyll prediseñados para obtener inspiración.