Reference

Reference guides contain the technical description - facts - that a user needs in order to do things correctly: accurate, complete, reliable information, free of distraction and interpretation. They contain propositional or theoretical knowledge, not guides to action.

Like a how-to guide, reference documentation serves the user who is at work, and it’s up to the user to be sufficiently competent to interpret and use it correctly.

Reference material is neutral. It is not concerned with what the user is doing. A marine chart could be used by a ship’s navigator to plot a course, but equally well by a prosecuting magistrate in a legal case.

Where possible, the architecture of reference documentation should reflect the structure or architecture of the thing it’s describing - just like a map does. If a method is part of a class that belongs to a certain module, then we should expect to see the same relationship in the documentation too.

Read more about references