El siguiente pasaje está citado en: https://diataxis.fr/explanation/#writing-good-explanation
Cuando escribes una explicación, estás ayudando a tejer una red de comprensión para tus lectores. Haz conexiones con otras cosas, incluso con otras cosas, incluso con cosas ajenas al tema inmediato, si eso ayuda.
Proporcione antecedentes y contexto en su explicación: explique por qué las cosas son así -decisiones de diseño, razones históricas razones históricas, limitaciones técnicas - extraiga consecuencias, mencione ejemplos concretos.
Las guías explicativas son sobre un tema en el sentido de que están alrededor de él. Incluso los nombres de sus guías explicativas de sus guías explicativas debería reflejar esto; debería poder colocar un sobre implícito (o incluso explícito) delante de cada título. Por ejemplo: Sobre la autenticación de usuarios, o Sobre las políticas de conexión a la base de datos.
La explicación puede contemplar alternativas, contraejemplos o múltiples enfoques diferentes a la misma pregunta. No estás dando instrucciones ni describiendo hechos: estás abriendo el tema para su consideración. Es útil pensar en la explicación como un debate: los debates pueden incluso considerar y sopesar opiniones contrarias.
Uno de los riesgos de la explicación es que se pueden colar otras cosas. La explicación debe hacer cosas que las otras partes de la documentación no hacen. No es el lugar de una explicación instruir al usuario en cómo hacer algo. Tampoco debe proporcionar una descripción técnica. Estas funciones de la documentación ya están contempladas en otras secciones.