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:
- ESLint
- Escritor 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/configuration), en el estado actual, proporciona mucha información en una sola página. A pesar de la presencia de encabezados, subtítulos y párrafos adecuados en la página, la documentación puede ser abrumadora. No hay forma de navegar a una sección determinada de la página, lo cual resulta frustrante para un usuario interesado en una sección determinada. La información, debido a esta falta de organización, también puede perderse, ya que no cumple con su propósito y se les pide a los usuarios que realicen un esfuerzo adicional.
Sin embargo, estos problemas se pueden resolver siguiendo una serie de pasos cuidadosos. Propongo que el primer paso de esta reorganización realice una auditoría de contenido. 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í mismo (por ejemplo, información desactualizada o incompleta). Después, pienso crear la Arquitectura de la Información (IA) para revelar la red de conocimiento. Esto nos permitirá agrupar la información en función de diversos temas y encontrar vínculos entre diversos 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 páginas. De esta forma, puedes vincular todo el paquete y compararlo con referencias cruzadas en Markdown. Como resultado, habrá una versión mejor organizada de la documentación de configuración, una más fácil de navegar y comprender.
Motivación A pesar de que utilizo software de código abierto desde hace ya algún tiempo, mi familiaridad con el término es bastante nueva, similar a mis conocimientos sobre el software de lint. Cuando comencé a aprender Python (a través de edX), me pregunté cómo unos pequeños errores pueden arruinar el código completo. Pensé que sería bueno que pruebes tus códigos de alguna manera y que se identificaran tus errores, y luego supe el término “linting”. Aún no he usado bien 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 defensora de los usuarios, y trata de facilitarles la vida a las personas. Mis habilidades y experiencia serán 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. Para el éxito del proyecto, es importante que la navegación por el contenido sea fácil y esté libre de complicaciones. Los objetivos importantes del proyecto son los siguientes. - Realizar una auditoría de contenido completa - Crear una arquitectura de la información para comprender el flujo de la 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 y que permite que ESLint sea personalizable. Los usuarios interesados en la configuración sin duda 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, de modo que se le proporcione 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 puede hacer que los usuarios se sientan 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, a través del debate sobre la especificación de analizadores, entornos y globales. Toda la práctica es cansador 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 ver temas similares, no será una tarea fácil para él, ya que no se proporciona esa 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 que se analizarán a continuación.
Auditoría de contenido El primer paso del proceso de reorganización de la documentación de configuración es realizar una auditoría de contenido exhaustiva. El objetivo de la auditoría es identificar algunos problemas clave, como contenido obsoleto, duplicaciones, 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 obtener sus 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 (IA) puede ser valiosa. Los resultados de la auditoría de contenido servirán como una buena base para comprender y desarrollar el flujo de la información. Luego, 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 ir seguido del vínculo que dirige a "Cómo inhabilitar reglas con comentarios intercalados". También se pueden identificar otros vínculos de este tipo, lo que crea relaciones entre diferentes 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 dirijan 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.
Se creará toda la documentación con Markdown para mantener las cosas simples y bien organizadas. Se tendrán mucho cuidado para garantizar que la documentación se pueda reutilizar, ya que podría crecer y alterarse en el futuro.
Herramientas para usar Algunas herramientas importantes que pueden resultarte útiles mientras trabajas 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
- 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 y se mantenga el flujo correcto en el proceso.
Del 10 de julio al 16 de agosto de 2020: Revisión y selección de propuestas Revisaré la documentación de ESLint y desarrollaré las habilidades necesarias para completar el proyecto (como la escritura en Markdown y la colaboración en GitHub). También colaboraré con la documentación a través de GitHub y también interactuaré con otras personas para comprenderla mejor.
Del 17 de agosto al 13 de septiembre de 2020: Entablar relaciones con las comunidades Durante el período de vinculación comunitaria, definiré mejor mi propuesta de acuerdo con las conversaciones con los mentores y los equipos interesados. También editaré los objetivos y los hitos si es necesario. Además, me aseguraré de hacer una lista reducida de las herramientas que luego se utilizarán para trabajar en el proyecto.
Del 14 de septiembre 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 resaltar los problemas con el contenido y su presentación.
Del 20 de septiembre 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 asignar vínculos y referencias entre las distintas secciones de la documentación. También crearé una jerarquía de todas las secciones para 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 equipos interesados. Sus comentarios ayudarán a perfeccionar el plan y realizar modificaciones cuando sea necesario.
Del 6 de octubre al 20 de octubre de 2020: Reescritura y edición Durante este período, editaré y actualizaré las secciones de los documentos en las que se necesite trabajar. Es posible que se reescriban algunas secciones de la documentación de configuración o que se le agreguen algunos elementos nuevos. El enfoque de esta fase será garantizar que la documentación sea precisa, actualizada, flexible y reutilizable.
Del 21 de octubre al 25 de octubre de 2020: Correcciones y vínculos En esta fase, revisaré mi propio trabajo para deshacerme de errores gramaticales y estructurales, y también para volver a verificar la precisión de mi trabajo. También agregaré vínculos y referencias entre las secciones, de acuerdo con la IA, 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 de envío Vincularé todos los archivos de Markdown, crearé un índice y compartiré los borradores con los mentores. Esto servirá como envío del primer borrador, en forma de un paquete completo.
Del 1 de noviembre al 5 de noviembre de 2020: Primera revisión Durante estos cinco días, analizaré el primer borrador con mis mentores. Voy a recibir sus comentarios y a debatir mis ideas con ellos para crear una lista de los cambios que deben hacerse.
Del 6 de noviembre 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 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 ediciones realizadas a la primera versión y también destacarán cualquier otro problema que pueda haber surgido en el proceso de edición.
Del 16 de noviembre al 19 de noviembre de 2020: 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. Al finalizar esta fase, los documentos 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: Carga en el 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 al 28 de noviembre de 2020: Informe del proyecto En este período de cinco días, se creará un informe detallado del proyecto. 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 al 30 de noviembre de 2020: presentación final Se enviarán el proyecto, junto con todos los archivos y el informe del proyecto a los mentores. 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 los debates con los mentores en los períodos de vinculación con la comunidad y de 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 administración de contenido y comunicación, los estudios de usabilidad web y para dispositivos móviles, y el diseño de instrucciones. Trabajé como subeditor de una publicación en línea (Global Village Space) y como pasante de comunicaciones para Duke Forge en la Universidad de Duke. Además, también me interesa la escritura creativa.