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:
- ESLint
- Redactor técnico:
- Khawar
- Nombre del proyecto:
- Reorganizar o reescribir la documentación de configuración
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Se puede abstraer
El objetivo de este proyecto es reestructurar la documentación de configuración de ESLint y crear una arquitectura de la información eficaz. Esto facilitará la navegación y también mejorará la usabilidad y utilidad de la documentación.
Resumen del proyecto La documentación de configuración de ESLint (https://eslint.org/docs/user-guide/implementation), en el estado actual, brinda mucha información en una sola página. A pesar de la presencia de encabezados, subtítulos y párrafos apropiados en la página, la documentación puede resultar abrumadora. No hay forma de navegar a una sección determinada de la página, lo que resulta frustrante para un usuario interesado en una sección en particular. La información, debido a esta falta de organización, también puede perderse, ya que no puede cumplir con su propósito y se les pide a los usuarios que hagan un esfuerzo adicional.
Sin embargo, estos problemas se pueden resolver con una serie de pasos cuidadosos. Propongo que se realice una auditoría de contenido como el primer paso de esta reorganización. Una auditoría de contenido no solo ayuda a identificar los problemas en la presentación de la información, sino que también destaca las deficiencias del contenido en sí (por ejemplo, información desactualizada o incompleta). Después, pienso crear la arquitectura de la información (AI) para dar a conocer la red de conocimiento. Esto nos permitirá agrupar la información en función de diversos temas y encontrar vínculos entre varios temas estrechamente relacionados. La información obtenida a través de estas dos prácticas se utilizará para dividir la documentación de una sola página en varias. Así, podrás vincular todo el paquete y compararlo con Markdown en Markdown. Como resultado, habrá una versión mejor organizada de la documentación de configuración, que será más fácil de navegar y comprender.
Motivación A pesar de que utilizo software de código abierto desde hace bastante tiempo, mi familiaridad con el término es bastante nueva, similar a mis conocimientos sobre software de lint. Cuando comencé a aprender Python (a través de edX), me pregunté cómo los pequeños errores pueden arruinar el código completo. Pensé que sería bueno que de alguna manera se probaran tus códigos y que se identificaran tus errores. Luego, supe el término “ejecución con lint”. Todavía no he usado bien el software de análisis con lint, pero estoy seguro de que esto me facilitará mucho la vida en el futuro.
Con mis antecedentes en Ingeniería Eléctrica y algo de experiencia en programación, puedo comprender mejor los problemas de la codificación y los requisitos de los programadores. Además, mi título de grado en Comunicación técnica y profesional me hace una defensora de los usuarios, y trata de facilitarles la vida a las personas. Mis habilidades y experiencia servirán como una buena combinación para este proyecto, lo que agregará valor a la documentación de ESLint.
Objetivos El objetivo general de este proyecto es garantizar que la documentación de la página de configuración de ESLint sea fácil de comprender y no abrume a los usuarios. Es importante para el éxito del proyecto que la navegación por el contenido sea fácil y sin complicaciones. Los objetivos importantes del proyecto son los siguientes. - Llevar a cabo una auditoría de contenido integral - Crear una arquitectura de la información para comprender el flujo de información - Mejorar la arquitectura de la información para reorganizar la documentación - Identificar vínculos y referencias entre diferentes secciones del contenido - Volver a escribir o editar partes de la documentación si es necesario para cumplir con los requisitos de reconfiguración
- Garantizar que el contenido sea flexible y reutilizable
Descripción del proyecto La configuración de ESLint es una función importante que permite que ESLint se pueda personalizar. Los usuarios interesados en la configuración estarían interesados en uno o dos aspectos en un momento determinado. Por lo tanto, es importante que se guíe al usuario a su tema de interés particular, para proporcionarle la solución de manera eficiente. El estado actual de la documentación de configuración de ESLint contiene mucha información útil, pero está organizado de manera tal que los usuarios se sienten abrumados, frustrados y perdidos. Por ejemplo, si alguien está interesado en aprender sobre el uso de complementos de terceros en ESLint, tendrá que desplazarse hacia abajo para abordar la especificación del analizador, los entornos y los globales. Toda la práctica es cansadora para los usuarios y puede alejarlos del sitio web. Del mismo modo, si un usuario se encuentra en algún punto en el medio de la página y quiere ir a una sección en particular o simplemente para ver temas similares, no será una tarea fácil para él, ya que no se proporciona tal ayuda a los usuarios. Estos problemas requieren atención inmediata, ya que la calidad de cualquier documentación, sin importar qué tan bien redactada, depende de su utilidad. Propongo soluciones para estos y otros problemas relacionados en el debate que sigue.
Auditoría de contenido El primer paso del proceso de reorganización de la documentación de configuración sería realizar una auditoría de contenido exhaustiva. El objetivo de la auditoría es identificar algunos problemas clave, como contenido obsoleto, duplicación, contenido faltante, etc. Una hoja de cálculo de auditoría de contenido creada como resultado se compartirá con los equipos de administración y documentación para que brinden comentarios. Esto te ayudará a idear una nueva estrategia para estructurar y presentar la documentación.
Creación de la arquitectura de la información Para comprender la red de conocimiento o el flujo de información en la documentación de configuración, la creación de la arquitectura de la información (AI) puede ser valiosa. Los hallazgos de la auditoría de contenido servirán como una buena base para comprender y desarrollar el flujo de la información. Se creará una versión mejorada de la IA para organizar y presentar la documentación de mejor manera. Esta IA mejorada no solo reestructurará el contenido actual, sino que también identificará vínculos y bifurcaciones entre varias secciones de la documentación, lo que creará una red eficiente. Por ejemplo, al contenido de "Reglas de configuración" puede seguirle un vínculo que lleve a la "Inhabilitación de reglas con comentarios intercalados". También se pueden identificar otros vínculos, lo que crea relaciones entre las distintas secciones de la documentación.
Una auditoría de contenido y una IA del índice proporcionarán la información adecuada para crear un índice detallado con vínculos que lleven a secciones y subsecciones específicas de la documentación. Crear archivos separados para cada sección y agregar las referencias adecuadas a otras secciones puede agregar valor a todo el conjunto de documentos. Se puede crear un índice para los usuarios que llegan a la documentación de configuración, lo que ayuda en su recorrido mientras están en el sitio web. El índice puede incluir todos los encabezados de primer y segundo nivel para que sea breve pero completo. Una de esas prácticas, por ejemplo, es la que usa Prettier (https://prettier.io/docs/en/index.html) para organizar la documentación.
Crearemos toda la documentación con Markdown para que todo sea simple y organizado. Se tendrá mucho cuidado para garantizar que la documentación se pueda reutilizar, ya que podría crecer o modificarse en el futuro.
Herramientas para usar Algunas herramientas importantes que pueden ser útiles para trabajar en el proyecto son: - Draw.io para crear ilustraciones para la IA según sea necesario - Atom (o un editor similar) para escribir y editar documentos en Markdown
- Usar GitHub para garantizar el control de versiones de la documentación
Hitos Desde el envío de la propuesta hasta la finalización del proyecto, los siguientes hitos tentativos garantizarán que el proyecto se complete a tiempo, manteniendo el flujo correcto en el proceso.
Del 10 de julio al 16 de agosto de 2020: Revisión y selección de propuestas Repasaré la documentación de ESLint y desarrollaré las habilidades necesarias para completar el proyecto (como la redacción de Markdown y la colaboración en GitHub). También contribuiré con la documentación a través de GitHub y también interactuaré con otras personas para comprender mejor la documentación.
Del 17 de agosto al 13 de septiembre de 2020: Vínculos con la comunidad Durante este período, definiré mejor mi propuesta en función de las conversaciones con los mentores y los equipos involucrados. También editaré los objetivos y los hitos si es necesario. Además, me aseguraré de preseleccionar las herramientas que luego se usarán para trabajar en el proyecto.
Del 14 de septiembre de 2020 al 19 de septiembre de 2020: Auditoría de contenido Para comenzar con el proyecto, realizaré una auditoría de contenido integral de la documentación de configuración. El objetivo sería destacar los problemas con el contenido y su presentación.
Del 20 de septiembre de 2020 al 25 de septiembre de 2020: Arquitectura de la información (IA) Después de la auditoría de contenido, crearé la IA de la documentación de configuración. Me centraré en presentar la red de conocimiento de una manera comprensible. Esto ayudará a realizar mejoras en el flujo de información.
Del 26 de septiembre de 2020 al 30 de septiembre de 2020: Vínculos y referencias Analizaré la IA durante esta fase para trazar vínculos y referencias entre las distintas secciones de la documentación. También crearé una jerarquía de todas las secciones, lo que mejorará la AI en el proceso.
Del 1 de octubre de 2020 al 3 de octubre de 2020: El mapa final Con la ayuda de las estadísticas obtenidas a través de la auditoría de contenido y la IA, crearé un mapa final para implementarlo en la documentación de configuración reorganizada. Este mapa integral contendrá un índice, una jerarquía de temas y una lista de vínculos y referencias cruzadas entre las secciones de la documentación.
Del 4 de octubre de 2020 al 5 de octubre de 2020: Debate En este punto, antes de editar la documentación, presentaré mis hallazgos y la planificación a los mentores y los equipos en cuestión. Sus comentarios ayudarán a perfeccionar el plan y realizar alteraciones cuando sea necesario.
Del 6 de octubre de 2020 al 20 de octubre de 2020: reescritura y edición En este período, editaré y actualizaré las secciones de los documentos en las que se necesite trabajo. Es posible que se reescriban algunas secciones de la documentación de configuración o se le agreguen algunos elementos nuevos. El enfoque en esta fase será garantizar que la documentación sea precisa, actualizada, flexible y reutilizable.
Del 21 de octubre de 2020 al 25 de octubre de 2020: Correcciones y vínculos En esta fase, revisaré mi trabajo para deshacerme de errores gramaticales y estructurales, y verificar su exactitud. También agregaré vínculos y referencias entre secciones, según la AI, para asegurarme de que la documentación siga el mapa de conocimiento diseñado anteriormente.
Del 26 de octubre al 31 de octubre de 2020: Versión final para el envío Vincularé todos los archivos de Markdown, crearé un índice y compartiré los borradores con los mentores. Esto servirá como el envío del primer borrador, en forma de un paquete completo.
Del 1 de noviembre de 2020 al 5 de noviembre de 2020: Primera revisión Durante estos cinco días, analizaré el primer borrador con mis mentores. Obtendré sus comentarios y analizaré mis ideas con ellos para crear una lista de los cambios que deben hacerse.
Del 6 de noviembre de 2020 al 12 de noviembre de 2020: Primeras ediciones Con la ayuda de los comentarios de los mentores, editaré el primer borrador de la documentación. Las ediciones reales dependerán de la naturaleza de los comentarios, pero los objetivos de reutilización, precisión y flexibilidad serán el lugar de la fase de edición.
Del 13 de noviembre de 2020 al 15 de noviembre de 2020: Segunda revisión Después de completar las ediciones iniciales, analizaré el progreso con mis mentores y los equipos correspondientes una vez más. Estos debates se centrarán en las modificaciones realizadas a la primera versión y también destacarán otros problemas que hayan surgido en el proceso de edición.
Del 16 de noviembre de 2020 al 19 de noviembre de 2020: Segunda modificación Luego, dedicaré un período de cuatro días a editar el documento. Las versiones producidas como resultado se analizarán con los mentores para darles una forma final. Los documentos, al final de esta fase, estarán en la forma final, listos para subirse al sitio web y al repositorio de GitHub.
Del 20 de noviembre de 2020 al 23 de noviembre de 2020: Subida al sitio web Después de realizar todas las modificaciones necesarias, los documentos se subirán al sitio web. Los problemas que se detecten en el proceso se abordarán en consecuencia, ya que tendremos algunos días para trabajar en la documentación.
Del 24 de noviembre de 2020 al 28 de noviembre de 2020: Informe del proyecto Se creará un informe detallado del proyecto en este período de cinco días. Los objetivos, las dificultades, los problemas y las soluciones presentadas formarán parte del informe del proyecto. El informe se compartirá con los mentores para recibir comentarios.
Del 29 de noviembre de 2020 al 30 de noviembre de 2020: Presentación final Se enviarán a los mentores el proyecto, junto con todos los archivos y el informe del proyecto. Se realizará una revisión de todo el proyecto a través de una reunión/debate con los mentores y los equipos involucrados.
A lo largo del proyecto, seguiré consultando a los mentores para obtener sus valiosos comentarios. Todos estos hitos se pueden modificar en función de las conversaciones con los mentores en los períodos de vínculo con la comunidad y revisión de propuestas.
Acerca de mí Tengo una licenciatura en Ingeniería Eléctrica y una licenciatura en Comunicación técnica y profesional de North Carolina State University. Tengo experiencia en los campos de la redacción y edición técnicas y profesionales, la comunicación y la administración de contenido, los estudios de usabilidad web y para dispositivos móviles, y el diseño de instrucciones. Trabajé como subeditor para una publicación en línea (Global Village Space) y como pasante de comunicaciones para Duke Forge en Duke University. Junto con eso, también me interesa la escritura creativa.