El siguiente pasaje está citado en: https://diataxis.fr/reference/#writing-a-good-reference-guide
La forma en que un mapa se corresponde con el territorio que representa nos ayuda a utilizar el primero para orientarnos a través del segundo. Lo mismo debería ocurrir con la documentación: la estructura de la documentación debe reflejar la estructura del producto, para que el usuario pueda orientarse al mismo tiempo.
En el caso del código, esto significa organizar las secciones de la documentación de referencia para seguir la arquitectura del software, siempre que sea posible.
No significa forzar la documentación en una estructura poco natural. Lo importante es que la La disposición lógica y conceptual del código y sus relaciones deben ayudar a que la documentación tenga sentido. documentación.
El material de referencia se beneficia de la coherencia, la terminología, el tono. Hay muchas oportunidades en la escritura para deleitar a sus lectores con su con su extenso vocabulario y su dominio de múltiples estilos, pero el material de referencia no es una de ellas. una de ellas.
Las referencias técnicas tienen una función: describir, y hacerlo de forma clara, precisa y
y de forma exhaustiva. Todo lo demás -explicar, discutir, instruir, especular- se interpone en el camino de ese trabajo y dificulta que el lector encuentre la información que necesita.
Puede ser tentador introducir instrucciones y explicaciones, simplemente porque la referencia técnica puede parecer demasiado escueto. En lugar de ello, enlace a guías de instrucciones, explicaciones y tutoriales introductorios según apropiados.
Los ejemplos son formas valiosas de proporcionar ilustraciones que ayuden a los lectores a entender la referencia, sin distraerse de la tarea de describir. Por ejemplo, un ejemplo de uso de un comando puede ser una forma sucinta de ilustrarlo y de su contexto.
Cualquier discrepancia entre la maquinaria y su descripción llevará inevitablemente al usuario por el mal camino.