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

Subject: Re: How do you define your audience/"user requirements" in your docs, to the reader?
From: "Sandy Harris" <sandyinchina -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 3 Apr 2008 07:08:11 +0800

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.


References:
How do you define your audience/"user requirements" in your docs, to the reader?: From: Leonard C. Porrello
Re: How do you define your audience/"user requirements" in your docs, to the reader?: From: John Posada
RE: How do you define your audience/"user requirements" in your docs, to the reader?: From: Leonard C. Porrello

Previous by Author: RE: STC is broken
Next by Author: amusing? docs story
Previous by Thread: RE: How do you define your audience/"user requirements" in your docs, to the reader?
Next by Thread: RE: How do you define your audience/"user requirements" in your docs, to the reader?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads