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:
- gRPC-Gateway
- Redactor técnico:
- iamrajiv
- Nombre del proyecto:
- Refactorización del sitio de documentos existente de gRPC-Gateway
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
ABSTRACT:
El sitio de documentos para el usuario está diseñado para ayudar a los usuarios finales a usar un producto o servicio. Un buen sitio de documentación para el usuario es muy importante porque les brinda a los usuarios una forma de aprender a usar el 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. Un buen sitio de documentos del usuario es una señal de buen estado del producto, el equipo de desarrolladores. Sin un buen sitio de documentos del usuario, es posible que el usuario no sepa cómo hacer todo lo anterior de manera efectiva y eficiente. El sitio de documentos del usuario puede desempeñar un papel fundamental a la hora de garantizar el éxito de un producto porque una buena comunicación es y siempre será el núcleo de cualquier negocio o producto. Una buena documentación simplemente toma esa comunicación y la coloca en un marco manejable al que todos pueden acceder para tener éxito.
En el momento de escribir este artículo, el repositorio de gRPC-Gateway se había bifurcado aproximadamente 1,200 veces y 184 personas habían contribuido a él. Esto demuestra que muchas personas de todo el mundo usan gRPC-Gateway y que es posible que deseen leer su documentación para el usuario para obtener orientación sobre cómo usarla. Sin embargo, la documentación para el usuario y el sitio de documentación de gRPC-Gateway están desactualizados y son incompletos. La comunidad de gRPC-Gateway quiere usar este proyecto para refactorizar el sitio de documentación existente y mejorarlo para que los usuarios finales tengan una experiencia fluida cuando usen gRPC-Gateway.
ESTADO ACTUAL:
Actualmente, el sitio de documentación de gRPC-Gateway tiene dos problemas principales:
• El primer problema es que el sitio web de la documentación es malo y desactualizado, es decir, el estilo y la estructura del sitio y el tema que se usa son obsoletos, incompletos, difíciles de navegar o encontrar información, y no abarcan muchas de las características de un buen sitio web de documentación. La refactorización del sitio de documentos existente de gRPC-Gateway incluirá el diseño del sitio web, la adición de funciones como la búsqueda de documentos, etc., la mejora de la IU del sitio web, la organización de instructivos y ejemplos en una barra lateral adecuada y la actualización de los diagramas de flujo y las imágenes existentes mediante el diseño de uno nuevo, etc. Este será mi objetivo principal y mi trabajo se basará más en el diseño y la reestructuración del sitio de Documentos existente.
• El segundo problema es que se debe refactorizar la documentación, los instructivos y los ejemplos existentes, etc., de gRPC-Gateway, lo que se puede hacer quitando los errores tipográficos y gramaticales de los archivos, alineando correctamente los fragmentos de Go y refactorizando los fragmentos de Go según los formatos de Gofmt. Además, si es así, podemos agregar más documentación, instructivos y ejemplos si es necesario, o reutilizar los archivos existentes después de refactorizarlos. Este es mi objetivo secundario y lo haré después de completar mi objetivo principal, es decir, aplicar diseño y reestructurar el sitio de Documentos existente.
¿POR QUÉ MI SITIO DE DOCUMENTOS PROPUESTO ES UNA MEJORA CON RESPECTO AL ACTUAL?
El sitio web de documentos del usuario propuesto se estructurará para mejorar y garantizar la eficiencia, la coherencia y la tranquilidad para el usuario final. Se verá mejor y tendrá una IU con secciones y funciones bien estilizadas que contienen guías escritas y sus diagramas de flujo y las imágenes asociadas.
La documentación de gRPC-Gateway proporciona una buena descripción del método y el ejemplo. Sin embargo, todavía usa el tema Jekyll anterior y, en la actualidad, tenemos mejores temas de Jekyll para SSG (generador de sitios estáticos). Además, es necesario reestructurar las páginas y hacerlas más útiles para los usuarios agregando ejemplos y instructivos nuevos, y actualizando y reescribiendo el contenido anterior.
ESTRUCTURA Y PLAN DE LAS IDEAS Y OBJETIVOS PROPUESTOS:
OBJETIVO PRINCIPAL DE ESTE PROYECTO:
Los objetivos y las ideas anteriores se pueden implementar de las siguientes maneras:
Se cambió el tema actual de Jekyll a uno mejor y más sólido. El motivo para volver a usar los temas de Jekyll es que será fácil para los encargados de mantenimiento contribuir y comprender el flujo de trabajo del proyecto, dado que ya conocen el framework y el tema de Jekyll existentes, que es similar al nuevo tema de Jekyll.
Después de revisar diferentes temas de Jekyll en Internet, encontré que este paquete de temas https://idratherbewriting.com/documentation-theme-jekyll/ es el más adecuado para el sitio de documentación de gRPC-Gateway debido a la siguiente función:
• Markdown: Para que los redactores técnicos no tengan que preocuparse por la instalación. Pueden escribir simplemente en el archivo .md. Cualquier persona puede hacer clic en el botón de edición que se muestra en el sitio web (nueva función) y contribuir (editar o sugerir cambios en la página en GitHub) para mejorarla. Esto motivará a los usuarios a agregar contenido nuevo o a editar el contenido para mejorarlo.
• Búsqueda de documentación: El usuario debe tener un cuadro de búsqueda para que pueda encontrar contenido relevante de forma fácil y rápida.
• Sección de comentarios: Es posible que el usuario tenga la opción de comentar y compartir sus puntos de vista sobre publicaciones y tutoriales. Pueden leer las opiniones de otras personas sobre la documentación del proyecto.
• Nuevos blogs y notas de la versión: El sitio web se debe actualizar con nuevas entradas de blog y noticias sobre el desarrollo y el plan de actuación actuales. Por lo tanto, este tipo de blog debe estar presente en la página de destino.
• Desarrollo rápido: La mayoría de los frameworks de SSG (generador de sitios estáticos) se ejecutan en el servidor y los cambios en el archivo se reflejan de inmediato en la IU. El proceso de implementación y compilación también debería ser sencillo. En el futuro, si queremos cambiar el framework, usaremos Entonces, debería ser fácil. La mayoría de los frameworks admiten la escritura de Markdown, por lo que solo debes mover los archivos .md y hacer algunos cambios.
Aquí divido las páginas existentes del sitio web en secciones y páginas nuevas :
• Página de destino:
La página de destino debe señalar las funciones principales de gRPC-Gateway.
- Comienza a usar gRPC-Gateway (redireccionamiento a la guía del usuario)
- Instrucciones de instalación sencillas (comandos breves)
- Por qué usar gRPC-Gateway
- Proyecto con gRPC-Gateway
La idea básica es que, en lugar de escribir una descripción larga, muestres los puntos principales en la página de destino y proporciones el vínculo para obtener más detalles.
• Página de la guía del usuario de gRPC-Gateway:
- Guía de instalación.
- Guía de inicio rápido con gRPC-Gateway
• Página de la guía para desarrolladores de puerta de enlace de gRPC para desarrolladores:
La Guía de desarrollo, la Guía de contribuciones, la configuración de Git, el Código de conducta, la configuración de la documentación, el flujo de trabajo de desarrollo, etc., dirigen a páginas similares. Por lo tanto, es necesario refactorizar y reorganizar todos los archivos. La página de desarrollo principal debe contener todas estas páginas, y el hipervínculo se creará en cada paso.
• Acerca de la página de gRPC-Gateway:
Debe haber una lista de todos los colaboradores en las secciones del equipo Vínculos rápidos y notas de la versión, se agregarán los blogs más recientes para que el usuario pueda leer las noticias actuales de gRPC-Gateway.
• Página de blogs, notas de la versión y instructivos:
Pienso que el sitio web debería tener una opción de blog. De esta manera, las noticias y los comunicados se pueden comunicar fácilmente. La página del instructivo contendrá algunas charlas y artículos populares que aclaran los conceptos y las APIs de gRPC-Gateway. Los colaboradores pueden agregar sus vínculos a instructivos en la página correspondiente.
Después de completar la tarea anterior, actualiza los mismos cambios en la rama v2 y haz incluso con la rama principal de gRPC-Gateway.
OBJETIVO SECUNDARIO DE ESTE PROYECTO:
Se deben realizar otros cambios para que la documentación de gRPC-Gateway sea más sólida y legible:
• Se corrigieron los errores gramaticales y tipográficos, y se organizaron y alinearon los vínculos y las publicaciones en el sitio en todos los archivos existentes de gRPC-Gateway.
• Se agregó más documentación y contenido si es necesario en gRPC-Gateway, ya que la mayoría de las funciones tienen una documentación muy breve, como en la sección Documentación del sitio en AWS, en Acerca de y Uso, etcétera.
• Refactorización de fragmentos de Go gRPC-Gateway según los formatos de Gofmt
Después de completar la tarea anterior, actualiza los mismos cambios en la rama v2 y haz lo mismo con la rama principal de gRPC-Gateway.
POR QUÉ SOY LA PERSONA ADECUADA PARA ESTE PROYECTO:
Creo que soy la persona adecuada para este proyecto porque:
• Tengo experiencia previa en la mejora de la documentación de organizaciones y puedo usar cualquier sistema de control de versiones, por lo que no será un problema realizar comandos en GitHub. • Además, lo que me impulsa es trabajar en proyectos que crean valor para las personas. Creo que si quieres que alguien haga algo de la manera más eficiente posible, tú lo documentas. Cuando documentas tus procesos, garantizas la eficiencia, la coherencia y la tranquilidad de todas las partes involucradas. • Estoy familiarizado con el flujo de trabajo y la base de código de gRPC-Gateway, ya que he estado contribuyendo a gRPC-Gateway desde hace dos meses y se fusionaron 11 PR.