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:
- Puerta de enlace de gRPC
- Escritor técnico:
- iamrajiv
- Nombre del proyecto:
- Refactoriza el sitio de Documentos existente de gRPC-Gateway
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
RESUMEN:
El sitio de documentos de usuario está diseñado para ayudar a los usuarios finales a utilizar un producto o servicio. Un buen sitio de documentos de usuario es muy importante porque proporciona un medio para que los usuarios aprendan a utilizar el software, sus funciones, sugerencias y trucos, y también resolver problemas comunes que encuentran al utilizar el software. También reduce el costo de asistencia y forma parte de la identidad corporativa del producto. Un buen sitio de documentos de usuario es una señal de buen estado del producto, el equipo de desarrolladores. Sin un buen sitio de documentos de usuario, es posible que un usuario no sepa cómo hacer las cosas anteriores de manera efectiva y eficiente. El sitio de documentos de usuario puede desempeñar un papel fundamental a la hora de garantizar el éxito de un producto porque una buena comunicación es y será siempre el núcleo de cualquier negocio o producto, y 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 en que se redactó este documento, el repositorio gRPC-Gateway se bifurcó en aproximadamente 1,200 veces y 184 personas han contribuido a este repositorio. Esto muestra que muchas personas en todo el mundo utilizan gRPC-Gateway y es posible que quieran leer su documentación de usuario para obtener orientación sobre cómo usarla. Sin embargo, el sitio de documentos y documentación del usuario de gRPC-Gateway está desactualizado y está incompleto, y la comunidad de gRPC-Gateway desea usar este proyecto para refactorizar el sitio de documentos existente y mejorarlo a fin de permitir que los usuarios finales tengan una experiencia fluida cuando usen la puerta de enlace de gRPC.
ESTADO ACTUAL:
Actualmente, el sitio de documentos de gRPC-Gateway tiene dos problemas principales:
• El primer problema es el sitio web de documentos malo y desactualizado que consiste en el estilo y la estructura del sitio y el tema utilizado son obsoletos, están incompletos, son difíciles de navegar o encontrar información, no cubre muchas de las características de un sitio web de documentos buenos. La refactorización del sitio de Documentos existente de gRPC-Gateway incluirá el estilo del sitio web, la incorporació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 estilo y la reestructuración del sitio existente de Documentos.
• El segundo problema es la necesidad de refactorizar la documentación, los instructivos y los ejemplos existentes, etc. de gRPC-Gateway, que se puede hacer quitando errores tipográficos y gramaticales en los archivos, alineando adecuadamente los fragmentos de Go y refactorizando los fragmentos de Go de acuerdo con los formatos de Gofmt. Además, de ser así, podemos agregar más documentación, instructivos y ejemplos si es necesario o podemos reutilizar los archivos existentes después de refactorizarlos. Este es mi objetivo secundario y lo haré después de haber completado mi objetivo principal, es decir, darle el estilo y reestructurar el sitio actual de Google Docs.
¿POR QUÉ EL SITIO DE DOCUMENTOS PROPUESTO ES UNA MEJORA SOBRE EL ACTUAL?
El sitio web de los documentos del usuario propuestos se estructurará para mejorar y garantizar la eficiencia, la coherencia y la tranquilidad del usuario final. Tendrá un mejor aspecto y una interfaz de usuario mejorada con secciones bien estilizadas y funciones que contienen guías escritas y sus imágenes y diagramas de flujo asociados.
La documentación de gRPC-Gateway proporciona una buena descripción del método y el ejemplo. Sin embargo, todavía se usa el tema antiguo de Jekyll, y en la actualidad contamos con mejores temas de Jekyll de SSG (Static Site Generator). Además, es necesario reestructurar las páginas y hacerlas más útiles para los usuarios, ya que se agregan nuevos instructivos y ejemplos, y se actualiza y reescribe el contenido anterior.
ESTRUCTURA Y HOJA DE RUTA 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 de Current Jekyll por 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 existente, que es similar al nuevo tema de Jekyll.
Después de revisar los diferentes temas de Jekyll en Internet, descubrí que el paquete de temas https://idreferrerbecoding.com/documentation-theme-jekyll/ temas es el mejor para el sitio de documentos de gRPC-Gateway gracias a la siguiente función:
• Markdown:- Para que los escritores 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 para la página en GitHub) para mejorarla. Esto motivará a los usuarios para que agreguen contenido nuevo o editen el contenido para mejorarlo.
• Búsqueda de documentación:- El usuario debe disponer de un cuadro de búsqueda para encontrar contenidos relevantes de manera rápida y fácil.
• Sección de comentarios:- Los usuarios pueden tener la opción de comentar y compartir sus opiniones sobre publicaciones y tutoriales. Pueden leer las opiniones de otras personas sobre la documentación del proyecto.
• Nuevas notas de la versión y blogs:- El sitio web debe actualizarse con nuevas entradas de blog y noticias sobre el desarrollo y la hoja de ruta actuales. Así que el 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 inmediatamente en la IU. Además, el proceso de implementación y compilación debe ser sencillo. En el futuro, si queremos cambiar el framework, lo usaremos. Entonces debería ser fácil. La mayoría de los frameworks admiten la escritura en Markdown, por lo que solo mover los archivos .md y realizar pocos cambios debería ser suficiente.
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 características principales de gRPC-Gateway.
- Cómo comenzar a usar gRPC-Gateway (redireccionar a la guía del usuario)
- Instrucciones de instalación sencillas (comandos breves)
- Por qué usar gRPC-Gateway
- Proyecto con gRPC-Gateway
Por lo tanto, la idea básica es, en lugar de escribir una descripción larga, mostrar los puntos principales en la página de destino y proporcionar el vínculo para ir a los detalles.
• Página de la Guía del usuario de gRPC-Gateway:-
- Guía de instalación.
- Inicio rápido de gRPC-Gateway.
• Página de la Guía para desarrolladores de gRPC-Gateway:-
La guía de desarrollo, la guía de contribución, 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 dentro. Por lo tanto, es necesario refactorizar y reorganizar todos los archivos. La página de desarrollo principal debe contener todas estas páginas, y en cada paso se creará el hipervínculo.
• Acerca de la página de puerta de enlace de gRPC:
La lista de todos los colaboradores debe estar presente en las secciones del equipo Vínculos rápidos y notas de la versión, se agregarán los blogs más recientes para interactuar con el usuario y hacer que lea las noticias actuales de gRPC-Gateway.
• Página de blogs, instructivos y notas de la versión:-
Creo que ese sitio web debería ofrecer una opción de blog. Así, las noticias y los lanzamientos se pueden comunicar fácilmente. La página del instructivo contendrá algunas charlas y artículos populares que aclararán las APIs y los conceptos de gRPC-Gateway. Los colaboradores pueden agregar sus vínculos a los instructivos en la página del instructivo.
Después de completar la tarea anterior, actualiza los mismos cambios en la rama v2 e 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:
• Corrección de errores gramaticales y tipográficos, y de organización y alineación de vínculos y publicaciones en el sitio en todos los archivos existentes de gRPC-Gateway
• Agregar más documentación y contenido si es necesario en gRPC-Gateway, ya que la mayoría de las funciones tienen documentación muy corta, como en la sección Documentación del sitio en AWS, segundo plano y uso, etcétera.
• La refactorización de fragmentos de Go de gRPC-Gateway según los formatos de Gofmt.
Después de completar la tarea anterior, actualiza los mismos cambios en la rama v2 e incluso 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 por los siguientes motivos:
• Tengo experiencia previa en la mejora de la documentación de organizaciones y puedo usar cualquier sistema de control de versión, por lo que ejecutar comandos en GitHub no será un problema. • 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 forma más eficiente posible, debes documentarlo. Cuando documentas tus procesos, garantizas eficiencia, coherencia y tranquilidad para todos los involucrados. • Estoy familiarizado con el flujo de trabajo y la base de código de gRPC-Gateway, ya que estoy contribuyendo con gRPC-Gateway durante los últimos dos meses y combiné 11 PR.