La documentación es a menudo un dolor de cabeza para los desarrolladores, especialmente para proyectos de código abierto. Y para ayudar en esta área, Google abrió su propia guía de estilo
Desde hace algunos años, técnicos de Google han utilizado una guía de estilo editorial para la mayoría de su documentación para desarrolladores con el fin de apoyar a los colaboradores externos de sus proyectos de código abierto, como Kubernetes, AMP o Dart. Y para permitir una mayor coherencia entre la documentación de desarrolladores, ahora están haciendo pública esa guía de estilo.
Si aportas documentación a proyectos como éstos, ahora tenés acceso directo a consejos útiles sobre voz, tono, elección de palabras y otras consideraciones de estilo. Puede ser útil para problemas generales, como recordatorios para usar la segunda persona, tiempo presente, voz activa y la coma en serie; también puede ser ideal para comprobar problemas muy específicos, como si se escribe “app” o “aplicación” cuando se desea ser coherente con el estilo de Google Developers.
La guía de estilo es un documento de referencia, por lo que en lugar de leerlo en orden lineal, puede ser utilizado para buscar cosas según sea necesario. Para cuestiones de puntuación, gramática y formato, puede hacer una búsqueda en la página para encontrar elementos como “Comas”, “Listas” y “Vincular texto” en el navegador de la izquierda. Para términos y frases específicos, puede consultar la lista de palabras.
Otras compañías como WordPress y Salesforce, también han hecho públicas sus guías de estilo, aunque son pocas las que son tan específicas como las de Google, especialmente cuando se trata de lo básico.
El equipo detrás de la guía de estilo señala que este es un documento vivo y que cambiará con el tiempo. En la página de notas de la versión de la guía habrá actualizaciones y se pueden enviar comentarios y sugerencias a través del vínculo “Enviar comentarios” en cada página de la guía para seguir evolucionando.
El principal objetivo de esta guía es codificar y registrar las decisiones que el grupo de relaciones con desarrolladores de Google hace sobre el estilo. La guía puede ayudar a evitar decisiones sobre el mismo tema una y otra vez, puede proporcionar ayuda editorial en la estructuración y la escritura de tu documentación, y puede ayudarte a mantener la coherencia con la documentación de Google.
Ver: Google Developer Documentation Style Guide
Al mismo tiempo hay que recordar que todo en esta guía es una pauta, no una regla. En la mayoría de los contextos, Google no tiene la capacidad ni el deseo de aplicar estas directrices si no son apropiadas para el contexto.
Como la mayoría de las guías de estilo, esta guía de estilo tiene como objetivo mejorar la documentación, especialmente mejorando la consistencia; por lo tanto, puede haber contextos en los que tenga sentido divergir de estas directrices con el fin de mejorar su documentación.