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:
- ESLint
- Redactor técnico:
- Khawar
- Nombre del proyecto:
- Reorganiza o reescribe la documentación de configuración
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Resumen
El objetivo de este proyecto es reestructurar la documentación de configuración para ESLint y crear una arquitectura de la información eficaz. Esto facilitará la navegación y también mejorará la usabilidad y la utilidad de la documentación.
Resumen del proyecto La documentación de configuración de ESLint (https://eslint.org/docs/user-guide/configuring), en el estado actual, proporciona mucha información en una sola página. A pesar de la presencia de títulos, subtítulos y párrafos apropiados en la página, la documentación puede ser abrumadora. No hay forma de navegar a una sección en particular de la página, lo que resulta frustrante para un usuario interesado en una sección en particular. Debido a esta falta de organización, la información también puede perderse, no cumplir con su propósito y pedirles a los usuarios que dediquen más esfuerzo.
Sin embargo, estos problemas se pueden resolver con una serie de pasos cuidadosos. Propongo que el primer paso de esta reorganización sea una auditoría de contenido. Una auditoría de contenido no solo ayudará a identificar los problemas en la presentación de la información, sino que también destacará las deficiencias del contenido en sí (p.ej., información desactualizada o incompleta). Luego, planeo crear la arquitectura de la información (AI) para presentar la red de conocimiento. Esto nos permitirá agrupar la información según diversos temas y encontrar vínculos entre los temas estrechamente relacionados. Los conocimientos adquiridos a través de estas dos prácticas se utilizarán para dividir la documentación de una sola página en varias páginas. Luego, se puede vincular todo el paquete y hacer referencias cruzadas 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 entender.
Motivación A pesar de que he estado usando software de código abierto durante bastante tiempo, mi familiaridad con el término es bastante reciente, similar a mi conocimiento del software de linting. Cuando comencé a aprender Python (a través de edX), me pregunté cómo errores diminutos pueden arruinar todo el código. Pensé que sería bueno que pruebes tus códigos de alguna manera y que se identificaran tus errores, y luego descubrí el término "linting". Aún no he usado un software de análisis con lint de manera correcta, pero estoy seguro de que, en los próximos días, me facilitará la vida.
Con mi formación en Ingeniería Eléctrica y algo de experiencia en programación, puedo entender mejor los problemas de la codificación y los requisitos de los programadores. Además, mi título de posgrado en Comunicación Técnica y Profesional me convierte en un defensor de los usuarios, ya que intento facilitarles la vida a las personas. Mis habilidades y experiencia serán una buena combinación para este proyecto y agregarán valor a la documentación de ESLint.
Objetivos El objetivo principal 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 no tenga complicaciones. Los objetivos importantes del proyecto son los siguientes: - Realizar 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 - Rescribir o editar partes de la documentación, si es necesario para cumplir con los requisitos de reconfiguración
- Asegúrate de que el contenido sea flexible y reutilizable.
Descripción del proyecto La configuración de ESLint es una función importante que permite personalizarlo. Es muy probable que los usuarios interesados en la configuración quieran conocer uno o dos aspectos en un momento determinado. Por lo tanto, es importante guiar al usuario a su tema de interés particular y brindarle 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á organizada de una manera que puede hacer que los usuarios se sientan abrumados, frustrados y perdidos. Por ejemplo, si a alguien le interesa aprender sobre el uso de complementos de terceros en ESLint, tendrá que desplazarse hacia abajo y leer el debate sobre cómo especificar el analizador, los entornos y los globales. Toda la práctica es agotadora para los usuarios y puede alejarlos del sitio web. Del mismo modo, si un usuario se encuentra en algún lugar en el medio de la página y desea ir a una sección en particular o simplemente mirar temas similares, no le resultará una tarea fácil, ya que no se les proporciona tal ayuda. Estos problemas deben recibir atención inmediata, ya que la calidad de cualquier documentación, sin importar qué tan bien redactada esté, depende de su utilidad. En el siguiente debate, propongo soluciones para estos y otros problemas relacionados.
Auditoría de contenido El primer paso en el proceso de reorganización de la documentación de configuración sería realizar una auditoría de contenido integral. El objetivo de la auditoría será identificar algunos problemas clave, como contenido desactualizado, duplicación, contenido faltante, etc. Como resultado, se compartirá una hoja de cálculo de auditoría de contenido con los equipos de administración y documentación para obtener comentarios. Esto te ayudará a crear 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, puede ser valiosa la creación de una arquitectura de la información (IA). Los hallazgos de la auditoría de contenido servirán como una buena base para comprender y desarrollar el flujo de información. Luego, se creará una versión mejorada de la AI para organizar y presentar la documentación de una mejor manera. Esta IA mejorada no solo reestructurará el contenido actual, sino que también identificará los vínculos y los desvíos entre varias secciones de la documentación, lo que creará una red eficiente. Por ejemplo, después del contenido de “Configuración de reglas”, puede haber un vínculo que dirija a “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 índice y una AI 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 referencias apropiadas 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 a 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 exhaustivo. Una de esas prácticas, por ejemplo, es la que usa Prettier (https://prettier.io/docs/en/index.html) para organizar la documentación.
Toda la documentación se creará con Markdown para mantener la simplicidad y la organización. Se tendrá especial cuidado para garantizar que la documentación sea reutilizable, ya que podría crecer y alterarse en el futuro.
Herramientas para usar - Algunas herramientas importantes que pueden ser útiles mientras se trabaja 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 de 2020 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 de Markdown y la colaboración en GitHub). También contribuiré a la documentación a través de GitHub y me comunicaré con otras personas para comprenderla mejor.
Del 17 de agosto al 13 de septiembre de 2020: Integración en la comunidad Durante el período de integración en la comunidad, definiré mejor mi propuesta según las conversaciones con los mentores y los equipos involucrados. También editaré los objetivos y los eventos importantes si es necesario. Además, me aseguraré de elegir las herramientas que 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 integral del contenido de la documentación de configuración. El objetivo sería destacar los problemas con el contenido y su presentación.
Del 20 al 25 de septiembre de 2020: Arquitectura de la información (AI) Después de la auditoría de contenido, crearé la AI de la documentación de configuración. Me centraré en presentar la red del conocimiento de una manera comprensible. Esto ayudará a mejorar el flujo de información.
Del 26 de septiembre de 2020 al 30 de septiembre de 2020: Vínculos y referencias Analizaré la AI durante esta fase para asignar vínculos y referencias entre varias 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 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 que se implementará 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 al 5 de octubre de 2020: Discusión En este punto, es decir, antes de editar la documentación, presentaré mis conclusiones y mi plan a los mentores y a los equipos involucrados. Sus comentarios te ayudarán a definir mejor el plan y a hacer modificaciones cuando sea necesario.
Del 6 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 sea necesario. Es posible que se vuelvan a escribir algunas secciones de la documentación de configuración o que se agregue contenido nuevo. El enfoque en esta fase será garantizar que la documentación sea precisa, actualizada, flexible y reutilizable.
Del 21 al 25 de octubre de 2020: Correcciones y vínculos En esta fase, revisaré mi propio trabajo para eliminar los errores gramaticales y estructurales, y también para verificar su exactitud. También agregaré vínculos y referencias entre las secciones, según la AI, para asegurarme de que la documentación siga el mapa de conocimiento que se ideó antes.
Del 26 al 31 de octubre de 2020: Versión final para enviar Vincularé todos los archivos 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 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 las ediciones que deben hacerse.
Del 6 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. Los cambios reales dependerán de la naturaleza de los comentarios y las sugerencias, pero los objetivos de reutilización, precisión y flexibilidad serán el centro de la fase de edición.
Del 13 al 15 de noviembre de 2020: Segunda revisión Después de completar las ediciones iniciales, hablaré una vez más sobre el progreso con mis mentores y los equipos involucrados. Estas discusiones se centrarán en los cambios realizados en 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 de 2020 al 19 de noviembre de 2020: Segunda edición Luego, dedicaré un período de cuatro días a editar el documento. Las versiones que se produzcan como resultado se analizarán con los mentores para darles una forma final. Cuando finalice esta fase, los documentos estarán en su forma final, listos para subirse al sitio web y al repositorio de GitHub.
Del 20 al 23 de noviembre de 2020: Carga en el sitio web Después de hacer todas las modificaciones necesarias, los documentos se subirán al sitio web. Todos los problemas que surjan en el proceso se abordarán según corresponda, ya que aún tendremos unos días para trabajar en la documentación.
Del 24 al 28 de noviembre de 2020: Informe del proyecto Se creará un informe detallado del proyecto durante 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 que nos envíen sus comentarios.
Del 29 al 30 de noviembre de 2020: Envío final El proyecto, junto con todos los archivos y el informe del proyecto, se enviará a los mentores. Se realizará una revisión de todo el proyecto mediante una reunión o conversación con los mentores y los equipos involucrados.
A lo largo del proyecto, seguiré consultando a los mentores para obtener sus valiosos comentarios. Todos estos eventos importantes se pueden modificar en función de las conversaciones con los mentores durante los períodos de vinculación con la comunidad y revisión de propuestas.
Acerca de mí Tengo una licenciatura en Ingeniería Eléctrica y una maestría en Comunicación Técnica y Profesional de la Universidad Estatal de Carolina del Norte. Tengo experiencia en los campos de la redacción y edición técnica y profesional, la comunicación y la administración de contenido, los estudios de usabilidad web y para dispositivos móviles, y el diseño de instrucción. 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, me interesa la escritura creativa.