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

["Sandy Harris" <sandyinchina -at- gmail -dot- com>]

Leonard C. Porrello <Leonard -dot- Porrello -at- soleratec -dot- 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.