How do you define your audience/"user requirements" in your docs, to the reader?

[Sandy Harris]

Leonard C. Porrello <Leonard.Porrello at soleratec.com> wrote:

>  Perhaps it could be helpful to the user to understand whether
> or not the documentation is targeted at him (granted the
> user reads the intro sections).

Here's what I put in one doc:

Throughout this documentation, I write as if the reader had at least a
general familiarity with Linux, with Internet Protocol networking, and
with the basic ideas of system and network security. Of course that
will certainly not be true for all readers, and quite likely not even
for a majority.

However, I must limit amount of detail on these topics in the main
text. For one thing, I don't understand all the details of those
topics myself. Even if I did, trying to explain everything here would
produce extremely long and almost completely unreadable documentation.

If one or more of those areas is unknown territory for you, there are
plenty of other resources you could look at:

Linux
    the Linux Documentation Project or a local Linux User Group and these links
IP networks
    Rusty Russell's Networking Concepts HowTo and these links
Security
    Schneier's book Secrets and Lies and these links

Also, I do make an effort to provide some background material in these
documents. All the basic ideas behind IPsec and FreeS/WAN are
explained here. Explanations that do not fit in the main text, or that
not everyone will need, are often in the glossary, which is the
largest single file in this document set. There is also a background
file containing various explanations too long to fit in glossary
definitions. All files are heavily sprinkled with links to each other
and to the glossary. If some passage makes no sense to you, try the
links.

For other reference material, see the bibliography and our collection
of web links.

Of course, no doubt I get this (and other things) wrong sometimes.
Feedback via the mailing lists is welcome.


-- 
Sandy Harris,
Nanjing, China