#Framework

Most documentation sites grow organically and end up as a pile of markdown files with no clear structure. ciderpress recommends an opinionated framework for organizing your docs so they stay useful as your project scales.

#Why this matters

Bad docs aren't usually a writing problem — they're an organization problem. A perfectly written guide buried in the wrong section is invisible. A concept doc mixed into a quickstart confuses more than it helps.

A framework gives you two things:

1. A place for everything — your team knows where to put new docs without asking
2. Reader expectations — users know what kind of content they'll find in each section

#Our take on Diataxis

This framework is heavily inspired by Diataxis, a documentation system created by Daniele Procida. Diataxis defines four content types along two axes: learning vs. working, and theory vs. practice.

We extend this with three additional types that most real-world projects need: Standards, Troubleshooting, and Runbooks.

#The eight doc types

Each type has its own structure, rules, and templates. See Types for details.

#How this maps to ciderpress

The framework maps directly to ciderpress sections. A typical project might look like:

sections: [
  { title: 'Getting Started' /* tutorials + quickstarts */ },
  { title: 'Guides' /* task-oriented how-tos */ },
  { title: 'Concepts' /* explanations */ },
  { title: 'Reference' /* API, config, CLI */ },
  { title: 'Standards' /* rules and conventions */ },
  { title: 'Troubleshooting' /* common issues and fixes */ },
]

See Recommended for the full recommended layout.

#References

• Diataxis — the framework that inspired this approach
• Types — detailed breakdown of each doc type
• Recommended — the recommended section layout