Cómo documentar tu código según Google, una guía gratuita

Documentar un programa informático significa generar un documento que se explica el abc de este software, qué se pretende que haga, cómo funciona, la arquitectura del mismo, los elementos que lo conforman y todo lo que sea necesario para que ese software pueda ser mejorado y continuado por nuevos desarrolladores.

Es sumamente importante tener una buena documentación, especialmente para proyectos de código abierto en los cuales participan muchos desarrolladores que muchas veces ni siquiera son parte del mismo equipo.

Y para ayudar en esta área, Google abrió su propia guía de estilo. Un manual para desarrolladores en el cual comparten sus buenas practicas a la hora de hacer la difícil tarea de documentar.

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.