explanation-docs

An explanation document builds deep comprehension of why and how a system works, focusing on design rationale rather than step-by-step instructions. You need one to introduce architectural patterns or foster team understanding of underlying concepts.

To write design rationale documentation, use structured markdown templates to articulate the reasoning behind design decisions and trade-offs. This approach shifts technical writing from task completion to explaining the problem solved and core mechanics.

The best way to document complex architectural concepts is generating in-depth conceptual guides that articulate underlying principles and design decisions. This builds user mental models and deep comprehension of systems rather than just providing task instructions.

Yes, you can use this approach to explain software architecture trade-offs by generating conceptual guides. It articulates why a specific architectural pattern was chosen over alternatives, detailing the problem it solves and its core mechanics.

Conceptual guides focus on building mental models and deep comprehension of underlying principles, whereas how-to tutorials provide step-by-step instructions for task completion. Explanation documents address the why and how of a system rather than just usage.

You should avoid writing explanation documents when your audience needs immediate task completion instructions rather than conceptual understanding. If the goal is simply to provide usage steps without explaining design rationale or trade-offs, standard how-to tutorials are more appropriate.