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:
- WordPress
- Redactor técnico:
- tacitonic
- Nombre del proyecto:
- Un conjunto completo y renovado de guías de estilo de documentación
- Duración del proyecto:
- Larga duración (5 meses)
Project description
Sinopsis:
WordPress es una organización global de software sin fines de lucro que se dedica a brindar a las comunidades globales software que enfatiza la accesibilidad, el rendimiento, la seguridad y la facilidad de uso. La causa de WordPress se esfuerza por democratizar la publicación y el software de código abierto en la Web. En nuestra era digital, un sitio web es, literalmente, la fachada en línea de una organización o persona, y WordPress cumple con la inmensa tarea de entregar contenido de manera eficiente a cientos de millones de usuarios (atribuidos al 35% de Internet que ejecuta) con su software. Para brindarles servicios a estos usuarios de manera más eficiente, la documentación resulta esencial y es utilizada por la mayoría de los desarrolladores, administradores y usuarios finales. Por lo tanto, la documentación se puede establecer como un factor principal del ecosistema de WordPress. La documentación actual de WordPress no incluye un conjunto universal y unificado de reglas y lineamientos de estilo para la publicación. El motivo de esta propuesta es crear un conjunto completo y renovado de lineamientos de estilo de documentación, aplicables de forma universal a la documentación de WordPress. La idea del proyecto implica consolidar todos los aspectos de los lineamientos de diseño y estilo, como la semántica, la sintaxis, los lineamientos de gramática, la puntuación, las reglas específicas de desarrollo, los atributos de diseño y los detalles de formato. También incorpora convenciones lingüísticas, como la voz, el tono, el tiempo, todas las partes de la oración, así como las convenciones de nombres. Las herramientas, los lenguajes y las plataformas que se usarán serán WordPress, GitHub, Markdown y también pueden consistir en PHP/MySQL, HTML/CSS y JavaScript.
Plan del proyecto:
Guías de estilo de la documentación del estado actual de WordPress: El equipo de documentación de WordPress ha implementado una metodología de publicación unánime, pero no declarada. Pero, de vez en cuando, se presuponen algunos elementos y el proceso se vuelve especulativo. No existe ningún estándar ni criterio fijo con el objetivo de escribir y publicar artículos para WordPress. El equipo de documentación escribió lineamientos de estilo específicos del proyecto, pero ninguno que se aplique de forma universal. La mayoría de los lineamientos de estilo existentes no están consolidados en un manual o están obsoletos y deben actualizarse. Por lo tanto, es necesario diseñar y desarrollar una guía de estilo unificada para estandarizar la documentación de WordPress.
Objetivos:
Más del 35% de los sitios web de Internet se ejecutan en WordPress, lo que a su vez indica que millones de desarrolladores y usuarios finales utilizan sus impresionantes funciones. La documentación es un elemento esencial para ayudar a estos desarrolladores y usuarios a cumplir con estas funcionalidades de manera eficiente y sin complicaciones, incluso en caso de inconvenientes. El objetivo general de esta propuesta de proyecto es estandarizar una guía de diseño y estilo, unificar las guías de estilo existentes y actualizarlas, así como agregar nuevas reglamentaciones y especificaciones para la documentación de WordPress. Esto permitiría una mayor facilidad de uso, simplicidad y uniformidad en la documentación de WordPress.
Implementación:
Según lo sugerido por el mentor (Jon Ang) para este proyecto, el proyecto se puede abordar en 4 fases: descubrimiento, definición, implementación y mantenimiento. Antes de comenzar el proyecto, durante el período previo a la pasantía, trabajaré con mi mentor y finalizaré un cronograma adecuado que se ajuste a mi cronograma y entregables posteriores. Me familiarizaré más con el sistema de WordPress y los protocolos de trabajo de este proyecto.
Cuando comience la pasantía, analizaré y redactaré el resumen del plan con mi mentor. Se determinarán los requisitos y las necesidades. En primer lugar, describiré el flujo de la documentación y el proceso de interacción del usuario. Posteriormente, se describirán los esquemas de página de diseño de cada sección, categoría y componente. Luego, mi mentor los revisará. Si es necesario, se volverán a diseñar los diseños y se agregarán o quitarán algunos componentes. Luego, realizaré una investigación sobre los usuarios para determinar la usabilidad y viabilidad del flujo de la interfaz. Posteriormente, se implementará el Manual de estilo de documentación (como se ilustra en el siguiente diagrama) por sección. También se pueden consultar las guías de estilo de otras organizaciones que estén bajo licencias de código abierto o Creative Commons para agregarlas a nuestra guía. Si durante este período surgen dificultades de usabilidad, los volveré a diseñar.
Las pruebas y optimizaciones se llevarán a cabo después de que se complete el libro de estilo y se integre con HelpHub. Se rectificarían las vulnerabilidades, los elementos o los componentes redundantes. Se realizarán pruebas de IU y código, y se corregirán los errores no deseados, si es necesario. Se realizará un control de calidad final de la guía de estilo completa en cuanto al lenguaje, la gramática, la ortografía, la puntuación, etcétera.
Las tareas pendientes debido a retrasos imprevistos se completarán en el período de compensación. Las funciones o características adicionales que se determinen como factibles a lo largo del proyecto se pueden implementar después de que se realicen las pruebas finales. Se creará un plan de implementación y se enviará el producto terminado.
Herramientas y metodologías:
La documentación se compilará y editará en una plataforma colaborativa, como Documentos de Google. Si es necesario publicar a través de GitHub, también se pueden implementar lenguajes de marcado como Markdown o GitHub Flavored Markdown. En el caso de los estándares de diseño y estilo, también se pueden consultar los lineamientos de estilo de código abierto. Por último, el documento completo se formateará y publicará con WordPress.
Tabla de componentes:
Esta es una lista exhaustiva de los componentes que se pueden implementar en la Guía de estilo. Lineamientos para documentos: Accesibilidad, estructura del documento, codificación, fuentes externas, hechos, fuentes, público global, inclusividad, legalidad, accesibilidad multiplataforma, no ambigüedades, no afirmaciones excesivas, diseño de página, corrección política, protocolos, seguridad, estructura de las oraciones, redacción concisa, tono y estilo, imparcialidad
Lenguaje y gramática: Abreviaturas y acrónimos, Afirmación y negación, Artículos, Mayúsculas, Cláusula, Discurso directo o indirecto, Primera, segunda o tercera persona, Géneros, Glosario, Sustantivos, Prefijos y sufijos, Preposiciones, Pronombres, Referencia, Argot y jerga, Ortografía, Términos técnicos, Tiempo, Verbos, Voz
Puntuación: apóstrofo y comillas, dos puntos y semipuntos, comas, elipses, signos de exclamación, guiones y guiones, paréntesis, puntos, signos de interrogación, barras
Formato: resúmenes, introducciones, prefacios, nombres de marcas, nombres de productos, leyendas, fragmentos de código, bloques de código, fecha y hora, zonas horarias, lugares, monedas, nombres de archivos, notas al pie, encabezados y títulos, elementos destacados (negrita, cursiva, subrayado, tachado, comillas), sangría, índice, vínculos y URLs, listas, viñetas, numeración, contenido multimedia (imágenes, videos) e ilustraciones, notas, advertencias, sugerencias, números y números de teléfono, textos en varios idiomas, traducciones, escrituras de idiomas, espaciado, tablas, texto, marcas comerciales, derechos de autor, patentes, citas, instructivos y procedimientos, elementos de la IU y unidades de medida
Interfaz de usuario: actividades, botones, fragmentos de código, bloques de código, interfaz de línea de comandos, diálogos, menús y menús desplegables, ventanas emergentes y alertas, pestañas, terminología, elementos de la IU, Windows
Código: CSS, HTML, JS, Markdown, MySQL, PHP, sintaxis, XML
Diccionario/Glosario de uso de palabras (de la A a la Z)