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:
- WordPress
- Escritor técnico:
- tacitónico
- Nombre del proyecto:
- Un conjunto completo y renovado de guías de estilo para la documentación
- Duración del proyecto:
- Larga duración (5 meses)
Project description
Sinopsis:
WordPress es una organización mundial de software sin fines de lucro que se dedica a brindar software a las comunidades de todo el mundo que promueve 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 individuo, y WordPress cumple una tarea inmensa de servir de manera eficiente a cientos de millones de usuarios (atribuido al 35% de la Internet que ejecuta) con su software. Para ofrecer un mejor servicio a estos usuarios, la documentación resulta esencial y la usan la mayoría de los desarrolladores, administradores y usuarios finales. Por lo tanto, la documentación puede establecerse 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 universalmente a la documentación de WordPress. La idea del proyecto implica consolidar todos los aspectos de las pautas de diseño y estilo, como semántica, sintáctica, pautas gramaticales, puntuación, reglas específicas de desarrollo, atributos de diseño y detalles de formato. También incorpora convenciones del lenguaje como la voz, el tono, el tiempo verbal y todas las categorías gramaticales, así como convenciones de nomenclatura. Las herramientas, los lenguajes y las plataformas que se usarán serán WordPress CMS, GitHub, Markdown y también podrían consistir en PHP/MySQL, HTML/CSS y JavaScript.
Planificación del proyecto:
Estado actual de las guías de estilo para la documentación de WordPress: El equipo de documentación de WordPress implementó una metodología unánime, pero no declarada. Pero, de vez en cuando, se supone que algunos elementos se suponen 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 ha redactado pautas de estilo específicas del proyecto, pero ninguna que sea universalmente aplicable. La mayoría de las pautas de estilo existentes no están consolidadas en un manual o están obsoletas 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 las asombrosas funciones de esta plataforma. La documentación es un elemento esencial para ayudar a estos desarrolladores y usuarios a cumplir con estas funciones 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 existentes y actualizarlas, así como agregar nuevas regulaciones y especificaciones para la documentación de WordPress. Esto permitiría un uso fácil, simple y uniforme 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 del comienzo del proyecto, durante el período previo a la pasantía, trabajaré con mi mentor y determinaré un cronograma y un cronograma adecuados siguiendo los lineamientos de mi cronograma y entregables posteriores. Me familiarizaré más con el sistema WordPress y los protocolos de trabajo de este proyecto.
Cuando comience la pasantía, analizaré y esbozaré 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 con el usuario. Luego, se describirán los esquemas de página de diseño de cada sección, categoría y componente. Luego, mi mentor revisará estos diseños. Si es necesario, se rediseñarán los diseños y se agregarán o quitarán algunos componentes. Luego, realizaré una investigación de usuarios para determinar la usabilidad y viabilidad del flujo de la interfaz. Luego, se implementará la Guía de estilo de la documentación (como se ilustra en el siguiente diagrama) según cada sección. También se puede hacer referencia a las guías de estilo de otras organizaciones que usan licencias de código abierto o de Creative Commons para agregar nuestra guía. Si durante este período se producen dificultades de usabilidad, las rediseñaré.
Las pruebas y optimizaciones se llevarán a cabo una vez que se complete la guía de estilo y se integre con HelpHub. Se rectificarían las vulnerabilidades, los elementos o componentes redundantes. Se llevarán a cabo pruebas de IU y código, y se corregirán errores y errores no deseados, de ser necesario. Se llevará a cabo un control de calidad final para la guía de estilo completa con respecto al lenguaje, la gramática, la ortografía, la puntuación, etc.
Las tareas pendientes debido a retrasos imprevistos se completarán en el período de margen. Las funcionalidades o características adicionales que se determinarían como factibles a lo largo del proyecto se pueden implementar después de que se hayan realizado las pruebas finales. Se debe elaborar 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 mediante GitHub, también puedes implementar lenguajes de marcación como Markdown o GitHub Flavored Markdown. Para los estándares de diseño y estilo, también se pueden hacer referencia a las pautas de estilo de código abierto. Finalmente, se le daría formato al documento completo y se publicaría con WordPress.
Tabla de componentes:
Esta es una lista exhaustiva de los componentes que se pueden implementar en la Guía de estilo. Lineamientos del documento: Accesibilidad, estructura del documento, codificación, fuentes externas, datos, fuentes, público global, inclusión, legalidad, accesibilidad multiplataforma, no ambiguo, sin declaraciones excesivas, diseño de página, corrección política, protocolos, seguridad, estructura de oraciones, redacción breve, tono y estilo, imparciales
Lenguaje y gramática: Abreviaturas y acrónimos, Afirmación y negación, Artículos, Mayúsculas, Cláusulas, Voz directa/indirecta, Primera y segunda persona/Tercera persona, Géneros, Glosario, Sustantivos, Prefijos y sufijos, Preposiciones, Pronombres, Referencias, Jerga, Términos de voz, Verbos
Puntuación: apóstrofo y comillas, coma y punto y coma, comas, puntos suspensivos, signos de exclamación, guiones y guiones, paréntesis, puntos, signos de interrogación, barras
Formas
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 y XML
Diccionario/glosario de uso de palabras: de la A a la Z