Post History

Source: https://writers.stackexchange.com/a/34132
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

# TL;DR

Short pages are better.

# The Ideal Structure

I would recommend the following:

- Each page should have a single, clearly defined purpose
- Each pages should have a clearly defined audience
- Pages should be linked to other, relevant pages
- Structure your pages like a tree, with overview pages nearer the root, providing more detail as you move towards the leaves
- Provide multiple contents pages that reflect the roles and interests of readers
- Provide a comprehensive search facility
- Encourage page users to contribute to the contents

In my experience, a wiki is an ideal vehicle to provide these features.

# Justification

- Most people find long pages daunting
- It is easier to find information on a short page
- Contents pages help clarify the structure of the documentation
- Overview and deep-dive are separated, and are likely to be consumed by different readers (or readers at different levels of knowledge)
- Programmers are familiar with this structure
- Contents trees and search make this structure very navigable
- Nobody minds clicking, especially programmers. The old two-clicks rule simply doesn't apply any more.
- A good global search makes in-page searching less important
- Documents produced in collaboration with their readers are generally better than those produced by a single author

# About Me

I am a programmer with over 20 years experience in the industry. The team to which I belong produces some of the best documentation I've ever seen. We do this using a MediaWiki-based wiki for all our documentation. Everyone in the team contributes, edits, clarifies, corrects etc. More importantly, we all _read_ the documentation, because we've developed it together to meet the needs we actually have, rather than the needs someone else things we might have.

Original score: 8