Cómo escribir documentación que los desarrolladores sí leen

La mayoría de la documentación se escribe una vez, se lee poco y inspira menos confianza cada mes. Hemos estado reconstruyendo la nuestra y, por el camino, reuniendo los hábitos que hacen que una página se lea hasta el final.

Empiece con algo que funcione

Los desarrolladores llegan con una tarea, no con curiosidad. Lo primero en la página debe ser el ejemplo más pequeño que resuelve la tarea, listo para copiar.

curl https://api.example.com/v1/health \
  -H "Authorization: Bearer $API_KEY"

Explíquelo después. Un párrafo de contexto antes del primer fragmento de código es donde los lectores se van.

Páginas cortas y con un solo propósito

Una página que responde a una pregunta se puede encontrar, enlazar y mantener al día. Una que responde a seis se convierte en un muro que nadie mantiene.

Una prueba útil de longitud

Si la página necesita un índice para poder navegarse, probablemente quiere ser dos páginas.

Escriba los ejemplos con valores reales

foo y bar no enseñan nada sobre lo que contiene un campo. Use un ID de oferta verosímil, un formato de fecha real, un cuerpo de error realista. Los lectores aprenden la forma de sus datos más por los ejemplos que por el esquema.

Muestre los casos de fallo

Toda página de API debería incluir al menos una respuesta de error y qué hacer al respecto. Los tickets de soporte suelen venir de personas que tropiezan con el camino desfavorable que la documentación nunca mostró.

Haga que la búsqueda perdone erratas y sinónimos

La gente busca lo que quiere hacer, no el nombre que usted le puso. Escriben «login» cuando su página dice «authentication». Añada alias al frontmatter de la página y revise cada mes en los registros de búsqueda las consultas sin resultados; cada una es una página que falta o un sinónimo que falta.

title: Authentication
aliases:
  - login
  - api key
  - sign in

Mantenga la documentación junto al código

La documentación que vive en el mismo repositorio que el código se actualiza en el mismo pull request. Esa es la idea detrás de DocsFlowy, que estamos construyendo: apuntarlo al markdown de un repositorio y publicar a partir de él un sitio con búsqueda. Contaremos más cuando haya algo que probar.

Una breve lista de comprobación

• ¿La primera pantalla contiene algo que se pueda copiar?
• ¿Tiene esta página un único propósito claro?
• ¿Son realistas los valores de los ejemplos?
• ¿Se muestra el caso de error?
• ¿Se puede encontrar buscando la palabra que usaría un recién llegado?