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:
- Creative Commons
- Escritor técnico:
- nimishnb
- Nombre del proyecto:
- Guía de uso del vocabulario
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Sinopsis del proyecto
Vocabulary tiene un gran potencial para utilizarse como biblioteca principal de componentes de IU para la creación de sitios web. Lo que necesita es una guía de instrucciones sólida pero fácil de entender para los profanos. La información importante para desarrolladores, como las guías de componentes, las especificaciones de uso y los ajustes de configuración, forman parte esencial de cualquier documentación. Esto no solo alentará a los usuarios existentes a tener una idea de cómo el vocabulario sigue creciendo y alcanzando nuevos hitos, sino que también promoverá el uso de Vocabulary en proyectos más nuevos en comparación. Los resultados deseados de mi pasantía no solo implicarían escribir una guía directa para usar los componentes preexistentes, sino también diseñar y desarrollar una página principal (que genere una documentación integrada para cada una) para Vocabulary, Vue-Vocabulary y Fonts.
Planificación del proyecto
El problema: la documentación es una de las razones principales que determina el éxito de una determinada biblioteca de código abierto. La pregunta principal que se hacen los desarrolladores cuando eligen una pila de tecnología adecuada para compilar sus aplicaciones es “¿La biblioteca está bien documentada?”. ¿Está bien mantenido? ¿Tiene una compatibilidad considerable con el uso y los errores? Estas son exactamente las preguntas que deberíamos hacernos mientras trabajamos en esta idea de proyecto. Desde la perspectiva de la ingeniería de software:
Análisis de requisitos: Existe una necesidad imperante de tener una documentación concisa y consolidada para 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 esencial. La página principal que vincula a esta documentación debe ser atractiva y captar el interés de las personas en un instante. La documentación debe estar bien organizada para permitir un flujo continuo.
Especificaciones: Según los requisitos, se pueden decidir las especificaciones. El contenido de la documentación se puede formar a partir de datos presentes en los sitios web de Netlify de CC, junto con algo de inspiración de documentos conocidos, como semantic-ui, scikit-learn, NumPy, bootstrap, 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 Vocabulary, Vue-Vocabulary y Fonts actualmente:
Falta documentación y, aunque hay algo, partes de ella están dispersas en los sitios web de Netlify. Esto no permite que los usuarios, desarrolladores o colaboradores externos usen nuestra biblioteca.
Para llegar a un componente determinado y copiar su código correspondiente, se requieren clics adicionales. Una simple búsqueda en Google con algo como “Tabs component CC Vocabulary” no devuelve la información deseada. Una opción de búsqueda dentro de las guías de documentación mejoraría mucho la UX.
Una descripción más detallada de los componentes, que incluya los detalles no obvios
No hay opción de ejecució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 que funcione.
La solución
Existen varias soluciones posibles. Sin embargo, mencionaré algunas aquí y presentaré mi solución final en la parte de la conclusión:
= Usar 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 diseño.
= Usar Sphinx También 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 es compatible con las búsquedas de documentación.
- El CSS predeterminado se puede anular con uno personalizado. Se puede controlar el HTML con archivos .rst.
Desventajas:
- Implicaría programar en Python y en formato de texto reestructurado (.rst), lo que será una desviación de los lenguajes sugeridos para el proyecto.
= Usar temas de Jekyll Los temas de Jekyll se integran en las páginas de GitHub, y hay plantillas preexistentes que se pueden personalizar según nuestras necesidades.
Ventajas:
- Temas de documentación listos para usar para todos los fines
- El CSS y los estilos predeterminados se pueden anular con los personalizados, y también se puede controlar el HTML.
- Extrae el CSS predeterminado de Primer para compilar las páginas.
- Integración sencilla con las páginas de GitHub
Desventajas:
- Es posible que no proporcione la mejor estructura de documentación.
=Usando las páginas de GitHub Las páginas de GitHub estándar para compilar nuestro sitio estático (HTML, CSS, JS).
Ventajas:
- Control total sobre casi todo lo que se cuestiona.
- Flexibilidad máxima para decidir el diseño, los colores y los estilos.
- Uso sencillo de los componentes de Vocabulary
- Incorporación sencilla de fragmentos de código y vínculos de ejecución en vivo.
Desventajas:
- Puede ser un enfoque más lento.
= Cómo usar Haroopad Esto brinda una solución alternativa de Markdown.
Ventajas:
- Implicaría una programación mínima y complicada.
- El enfoque estaría en escribir la documentación a la perfección.
Desventajas:
- Falta de control sobre los CSS
- Puede o no tener la mejor asistencia de la comunidad.
- Es posible que no admita MDX.
= Usar MKDocs Esto proporciona otra solución alternativa de Markdown.
Ventajas:
- Implicaría realizar tareas de programación mínimas (otra vez).
- Escribe más, código menos.
Desventajas:
- Falta de control sobre los CSS
- Es posible que no tenga el mejor apoyo de la comunidad.
- Usa Python. Es posible que se necesite iniciar una instancia de Amazon S3.
= Usar VueJS + StorybookJS Este enfoque se usa comúnmente en Vocabulary y sus repositorios hermanos.
Ventajas:
- Apegarse a tecnologías que garantizan que funcionan bien, según las experiencias laborales pasadas
- Familiaridad con la base de código
- No hay tecnología competente en este espacio.
Desventajas:
- También pueden existir opciones más simples para los mismos fines.
En conclusión, creo que el enfoque que incluye VueJS + Storybook (HTML, CSS y JS) parece ser el más adecuado, ya que también me siento cómodo con él. Sin embargo, esto también significaría que no nos perderemos por completo en el desarrollo de esta aplicación. También sería bastante sencillo usar componentes de CC-Vocabulary. Sin embargo, para decidir la estructura de la documentación, debemos tener en cuenta la forma en que el contenido se divide entre los subtítulos en la documentación de readthedocs. Me impresionó el sitio web de Semantic-UI (que usa StoryBook), ya que tiene un aspecto minimalista y se puede conocer fácilmente lo que se quiere después de unos pocos clics. Además de Semantic-UI, también miré Material Design, Primer, Bootstrap, Carbon Design, etc. para usarlos como guías de diseño de la IU y sistemas de diseño para mi trabajo. También podemos buscar temas de documentación de Jekyll listos para usar como inspiración.