Introducción a la escritura de buena documentación

Esta publicación fue aportada por el autor invitado Jeff Matson. Jeff es el jefe de documentación de GravityForms. Es el creador del complemento de WordPress Heartbeat Control y es fanático de los años 90.

A menudo, la documentación es la parte más subestimada del proceso de desarrollo. Cuando miramos a las estrellas de rock en la comunidad de WordPress, normalmente miramos a los desarrolladores, diseñadores y vendedores. Poco se sabe acerca de los escritores de documentación que derramaron su sangre, sudor y lágrimas para garantizar que todo funcione sin problemas.

Esta publicación trata sobre aquellos que día tras día miran interminables líneas de código para descifrar lo que el desarrollador estaba pensando y el verdadero significado detrás del código que existe.

Una buena documentación es más que palabras

Los buenos escritores de documentación brindan más que un manual de instrucciones, brindan una experiencia. He conocido a excelentes documentalistas, he entrenado a principiantes y la mayor diferencia entre ellos es comprender el cerebro de quienes lo leen. Al igual que una novela, la documentación tiene un flujo que mantiene al lector interesado e ingeriendo más información de la que se da cuenta.

La documentación de calidad se dirige a los usuarios que tienen más probabilidades de leerla. También proporciona un punto de referencia para aquellos que tienen menos probabilidades de leerlo. Por ejemplo, si se documenta un gancho en particular, normalmente se asume que un desarrollador lo leerá, pero ¿qué pasa con aquellos que tienen poca experiencia en desarrollo?

Un buen redactor de documentación proporcionará un punto de referencia para aquellos que necesitan un mayor empujón en la dirección correcta, sin necesidad de ponerse en contacto con el soporte para que se lo explique.

La documentación tiene un impacto mayor de lo que piensas

La mayoría simplemente ignora la documentación, empujándola hacia el abismo sin fin hasta que ya no puede más. Soy culpable de lo mismo en algunos casos. Lo que esas personas no se dan cuenta es que cada vez que su complemento o tema se deja sin documentar, la experiencia del usuario se resiente.

Echemos un vistazo a su ticket de soporte más común. Si documentases mejor ese problema, ¿desaparecerían esos boletos por completo? Probablemente no. ¿Recibiría menos tickets relacionados con el problema y aumentaría su productividad o la de su agente de soporte? Lo garantizo. Creo que a todos nos vendría bien menos tickets de soporte.

Como mencioné anteriormente, la documentación tiene un impacto dramático en la experiencia del usuario. Si el usuario es capaz de localizar la información de manera fácil y eficiente, habrá ahorrado su propio tiempo y el suyo. La esperanza de vida mundial promedio es de 66,57 años y sus usuarios preferirían estar haciendo otra cosa con sus vidas que jugar con documentación mal escrita.

Si un cliente ve que ha dedicado bastante tiempo y esfuerzo a su documentación, lo apreciará mejor, conscientemente o no. Una buena documentación muestra que te preocupas por ellos después de la venta inicial.

¿Alguna vez se ha quedado sin nada después de gastar el dinero que tanto le costó ganar y pronto se arrepintió de la compra? Pienso que todos tenemos. Con la documentación adecuada, puede evitar pasar ese sentimiento a sus clientes.

¿Cómo se puede escribir una mejor documentación?

El primer paso es dejar de evitarlo. Una vez que eres bueno en eso, escribir documentación es una experiencia más placentera de lo que piensas. De hecho, se convertirá en una segunda naturaleza. Como todo lo demás en el mundo, la práctica hace al maestro.

Uno de los primeros pasos que desea tomar cuando decide llevar su documentación al siguiente nivel es determinar sus puntos débiles. ¿Sobre qué te contactan? Si comienza a escribir a ciegas sobre cosas, es posible que descubra que lo que está escribiendo no tiene el impacto que le gustaría.

Una de las mejores técnicas que he descubierto es rastrear la cantidad de tickets que están documentados frente a los que no, y dividir los que no lo están en categorías. De esta manera, puede enfocarse mejor en sus puntos débiles y revisar las partes que pueden no ser tan útiles como deberían ser.

Una vez que haya determinado qué documentación debe escribir, debe determinar su público objetivo y dividirlo en desarrolladores, usuarios y usuarios avanzados. Esto le ayuda a atender a esa audiencia en particular. Veremos cómo dirigirse a esos usuarios un poco más tarde.

A continuación, desea desglosar el documento. Para los desarrolladores, querrá dividirlo en información sin procesar (argumentos aceptados, valores devueltos, etc.), ejemplos específicos y casos de uso. Para los usuarios, el mejor curso de acción es un tutorial. Cada paso que deban dar, independientemente de lo trivial que parezca, es fundamental.

Explícaselo en cada paso del camino. La documentación para usuarios avanzados es muy similar a un escenario de usuario, pero más estructurado y escaneable. Sea claro, pero permítales saltar fácilmente a donde necesitan ir sin leer primero el paso anterior.

El arte de escribir mejor documentación

Cuando se trata del arte de escribir su documentación, escriba de la manera que mejor se dirija a su audiencia, pero también use un lenguaje simple que sepa que entenderán. Una de las mejores razones para esto se debe a las traducciones. Si bien el traductor de Google hace un excelente trabajo, es mucho más fácil traducir el vocabulario simple de un estudiante de quinto grado que el contenido en una tesis de posgrado.

Dentro de su contenido, no tenga miedo de vincular a contenido relevante. Esto le permitirá evitar repetirse en varios documentos, así como permitir que el lector retroceda si necesita más información sobre un tema en particular. Después de todo, sus objetivos principales son hacer feliz al usuario y ahorrarse tiempo.

El proceso de documentación no se detiene después de presionar el botón de publicar . Regrese y revise cada documento según sea necesario. Casi inmediatamente después de que se publique el documento, regrese y vea si los tickets de soporte que rastreó han disminuido y el tráfico a ese artículo en particular ha aumentado. Por lo general, si obtiene más tráfico para un artículo, está ayudando. Si obtiene más tráfico pero la misma cantidad de tickets de soporte, puede consultar ese artículo para ver por qué.

Lo que hemos aprendido

Primero, espero que después de llegar hasta aquí, tenga una mejor apreciación de aquellos en las trincheras escribiendo la documentación que la mayoría de nosotros damos por sentado. Realmente es una forma de arte que muchos de nosotros que escribimos documentación para ganarnos la vida realmente disfrutamos y le dedicamos muchas, muchas horas.

También espero que termine este artículo pensando más en su documentación existente y en cómo se puede mejorar. La documentación adecuada puede ser extremadamente gratificante y, una vez que se pone en práctica, puede ser muy divertido escribirla.

Documente temprano, documente a menudo. Un gran producto es más que un gran código, también está bellamente documentado.