: 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

@Cooney417

Vote Up Vote Down

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.

(0)

Login to post a comment!