Minimalism in documentation is John Carroll’s approach to technical instruction, based on the observation that users don’t read manuals front-to-back — they start trying to do things immediately and consult documentation only when stuck [@carroll1990].
Carroll’s research at IBM in the 1980s found that learners using traditional comprehensive manuals performed worse than learners using stripped-down, task-oriented materials. The comprehensive manuals buried the information users needed under introductions, overviews, conceptual frameworks, and background — all of which users skipped in practice. The information was there, but users couldn’t find it when they needed it.
Minimalist documentation follows several principles:
- Choose an action-oriented approach. Let users start doing meaningful tasks immediately. Don’t front-load theory, background, or conceptual overviews.
- Anchor the tool in the task. Organize documentation around what users are trying to accomplish, not around the system’s features or architecture. This aligns with task analysis and the shift from writer-based to reader-based prose [@flowerhayes1981].
- Support error recognition and recovery. Users make mistakes. Documentation should anticipate common errors and help users recover, not just describe the happy path.
- Support reading to do, studying, and locating. Different users have different needs at different times. The same person may need a tutorial (reading to do), a concept explanation (studying), and a reference entry (locating). Minimalism doesn’t mean writing less — it means writing what each reader needs, in the form they need it, without forcing them through content they don’t.
Minimalism connects to cognitive load theory: extraneous material in documentation doesn’t just waste the reader’s time — it actively degrades learning by consuming working memory that could be used for understanding [@sweller1988]. It also connects to Janice Redish’s work on web content: users scan, select, and act — they rarely read comprehensively [@redish2012].
Minimalism is not the same as brevity. A minimalist manual may be long if the task domain is complex. The point is that every section earns its place by serving a reader need, and no section exists because the writer thought it was interesting or because the system architecture suggested it.
Related terms
- task analysis — minimalism organizes documentation around tasks, not system features
- cognitive load — minimalism reduces extraneous cognitive load by cutting material that doesn’t serve the reader
- writer-based prose — comprehensive manuals organized by system architecture are writer-based; minimalist documentation is reader-based
- usability testing — Carroll developed minimalism through iterative usability testing
- progressive disclosure — minimalism uses progressive disclosure to present information when the reader needs it