Re: Dissertation Research

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

TDIXON2296 -at- aol -dot- com wrote:
> 
> I am currently doing my dissertation for my degree in Communication Authoring
> and Design (formerly Technical Communication).  Could anyone please help me?
> I need to know if anyone has come across any difficulties in writing online
> compared to paper documents.  Not technical, but in the language used, taking
> into account how the document is used etc.  If you haven't experienced any
> problems, i would like to hear from you to.  This would help me a lot in
> doing my research

Read the list archives. This topic has been covered repeatedly, and in some
detail.

e.g. Here's a message of mine that deals with some of those issues. Other
writers in the thread had quite different opinions. You should read both.

Subject: Re: Writing Concepts for Single Sourcing/Online Help
   Date: Fri, 08 Dec 2000 12:41:40 -0500
   From: Sandy Harris <sandy -at- storm -dot- ca>
     To: Lisa Kemp <lnk -at- ONTARIO -dot- COM>
    CC:  TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>

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 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 
Conference East, June 4-5, Baltimore/Washington D.C. area.
http://www.pdfconference.com or toll-free 877/278-2131. 

---
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.