WWW Style guide

The reader's structure

Remember always the audience for whom you are writing. If they are novices in the subject, it will normally help if you are firm about the structure of your work, so that they can learn the structure of the knowledge itself. For example, if you feel that the subject falls into three distinct areas, then that is an important thing to teach.

If, however, your readers will already have some knowledge in the subject, then they will already have formed their own structure for it. In this case they will consciously or subconsciously know where they expect to find things. If your structure is different from theirs, enforcing it too strongly will confuse them and put them off.

You may in this case have to resist a strong tendency to put across your own structure strongly and to the detriment of all others. There are two solutions.

If you have a single well-defined audience in mind, who will share a similar world view, then try to write exactly for that world view rather than yours.

If you are simultaneously writing for more than one group, then you must provide for both.

When you make a reference, qualify it with a clue to allow some people to skip it. For example, "If you really want to know how it works inside, see the Internals guide", or "A step-by-step introduction is in the tutorial".

Provide links for both reader's views. Your work will be more connected than a simple tree, but with proper qualification, no one should get lost.

Provide two separate tree "roots". For example, you can write a step-by-step tutorial and a functionally direct reference tree for the same data. Both will at the lowest level have the same data, but while the first will deal with the simple things first, the second may be functionally grouped. This is just like having several indexes to a book. The tutorial might also include information which the reference work does not.

(Up to overview , back to Introduction , on to: writing each document )
Tim BL