Documentation Sample
This section is a working writing sample, not a description of one. Rather than link to scattered PDFs, I documented a real, open-source tool I created end to end and organized the result the way I organize production documentation: with the Diátaxis framework.
The subject is the Changelog Generator — a Python CLI that turns git history into a publish-ready changelog using an LLM. It is intentionally a real tool with real edge cases, so the docs have to do real work: onboard a first-time user, answer task-specific questions, serve as a lookup reference, and explain the design decisions underneath.
How this is organized
Diátaxis splits documentation into four modes based on what the reader needs right now. Mixing them is the most common reason docs feel cluttered — a tutorial that keeps stopping to explain architecture loses a beginner; a reference padded with narrative slows down an expert.
| Mode | Reader's question | Where it lives |
|---|---|---|
| Tutorial | "I'm new — walk me through it." | Getting started |
| How-to guide | "I have a specific task to finish." | How-to guides |
| Reference | "What does this flag do, exactly?" | CLI reference |
| Explanation | "Why is it built this way?" | How it works |
If you only read one page to judge the writing, read the getting-started tutorial for instructional voice, or the CLI reference for structured, scannable reference design.