Re: Writing Concepts for Single Sourcing/Online Help

[Sandy Harris <sandy -at- storm -dot- ca>]

Lisa Kemp wrote:
> 
> What are in a challenging situation. We are writing for single sourcing
> for the first time as we are also writing for onlie help for the first
> time for a new highly user-configurable product.

Sounds a bit like what I do.
http://www.freeswan.org/doc.html

Our stuff is not only user-configurable, but runs on several different
Linux distributions and half a dozen CPU architectures and interoperates
with about a dozen implementations from other people. Isn't complexity fun?

> So, we are examining how to write our concepts. Before, our concepts
> very procedural, and now we need to write more about what the concept
> is and how it is useful to the user.

One great thing about hypertext is that you can use it to factor the
docs. To a large extent this involves concepts we've just heard about
in the "Information Mapping" thread.

e.g. I cover basic concepts in an introductory section that I urge
everyone to read before using the software. (Of course, not all do.)
Then there are a couple of more detailed conceptual sections giving
heavier background. Some of the conceptual stuff is in the glossary,
so all the other sections can link to it.

There are links everywhere, including links from many glossary items
to more detailed explanations in the text, links from the theory
parts to examples elsewhere, links from the examples to glossary
or theory, ...

If you get this right, it saves huge amounts of effort explaining
the same thing N times. Of course, getting it right is hard.

Something a lot of people forget when they go to hypertext is that
it is still text. Large chunks of it have to be readable as text,
without jumping down a dozen links trying to make sense of it and
becoming utterly lost. Many of the links must, I think, be there,
and a lot of unnecessary detail can be moved out of the main flow
while remaining accessible via links for those who need it, but the
main flow must include enough detail to make sense standalone.

> Do you have guidelines you can share about how to write a GOOD
> concept for online help and single sourcing?

Some things I think I've learned:

Getting the reference material right is the first priority. I'm
lucky; the programmers do our man pages, and do them well, so I
don't need to worry much about that.

Reference material without friendlier and more task-oriented
docs is a disaster, but not nearly as bad as trying to either
write or use the task-oriented stuff with no reference available.
If you're lucky enough to have a good detailed user interface spec,
then most of the reference material can be extracted from that
quickly and easily.

On the other hand, once you have some sort of decent reference,
then adding stuff built around user tasks is more important
than any improvement you might want to make in the reference,
other than correcting outright errors and ommissions.

At least for my docs, the glossary turned out (somewhat to my
surprise) to be the largest single file by a fair margin.

> Are there good resources out
> there for this? We have not found much information that deal specifically
> with the paradigm shift from writing for print to writing for single
> sourcing and online help.

RANT
Unix was delivering what I've always considered the minimum standard
for computer documentation:

	complete (e.g. all file formats described in detail)
	everything available on-line
	all of it printable by the user
and	an extensive system of cross-references

as standard stuff in the early 80s when I learned it. I've never
understood why any customer would accept less from any vendor.
/RANT

Partly as a result of having that standard to live up to, the Open
Source movement has done quite a lot of work on single-sourcing.
Not all the tools are ready for prime time, but some are and the
ideas floating around are certainly worth a look. See for
example the "resources" and "Author Guide" sections of
www.linuxdoc.org or similar sections of www.oswg.org

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.