RE: Documentation structure

Subject: RE: Documentation structure
From: "Gale Stafford" <gstafford -at- gmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 18 Feb 2005 10:35:34 -0600


Caroline --

Regarding use cases, I'd recommend that you ask your Product Managers, what
purpose would the use cases serve? How would they "use" the use cases after
you've written them up? Who would be reading them? Once you define the
purpose of the use cases first, you'll be in a decent position to help the
Product Managers evaluate if they're really necessary; and if they are
necessary, you can write them more effectively, knowing the purpose, the
audience, etc.

As for formatting your use cases, it's good to follow certain standards and
recommended use case templates. I recommend a book "Use Cases -
Requirements in Context" by Kulak and Guiney. Also, Alistair Cockburn has a
good book on use cases.

Good luck!
Gale

Gale Stafford Consulting
http://www.gstafford.com

-----Original Message-----
From: Caroline Tabach
Sent: Sunday, February 06, 2005 7:26 AM
To: TECHWR-L
Subject: Documentation structure


Hi,
For a new data-base product different from the general range of products we
had up till now, the Product Managers in our company would like to add a
wider range of documents than those we have written for our products in the
past.
In addition to an Installation and Configuration guide and a User Guide,
people would like to see some additional documentation.

I have the following questions:
Up to now I have written a "Getting Started" as a very brief overview
chapter near the beginning of a user guide (with links to other chapters if
needed). Management are talking about a stand alone Getting Started book. Do
people write a "Getting Started" as a stand alone book and if so to what
level of details do you go.

They would like a Troubleshooting book.
I thought about structuring this according to various parts of our product,
with a table of possible problems and their solutions in each chapter, are
there other ways of structuring a troubleshooting guide?

They want a "Use Cases" book what is the accepted structure of such a book?
Can it be part of the general user guide (an example of using applications
at the end of each chapter?)

They need an ini file guide. The users can change certain ini file commands
to a certain extent, however, there are commands that they are not allowed
to touch. Would you give explanations for all of the commands, or only for
those that they can change?

We need to send them a site survey before installing the equipment, people
are unsure of the level of details required. Does anyone have experience of
such documents?

The company would really like to give the users "impressive" documentation!
Are there additional types of documents that you generally distribute with
software products that have not been mentioned here?

Thanks for your input
Caroline Tabach
e-mail: CarolineT -at- radcom -dot- com
http://www.radcom.com
http://www.protocols.com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more! Download your free trial today at www.componentone.com/techwrlfeb.

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



References:
Documentation structure: From: Caroline Tabach

Previous by Author: Re: Button vs. Icon
Next by Author: RE: New TECHWR-L Poll Question - Degrees
Previous by Thread: Re: Documentation structure
Next by Thread: Re: Documentation structure


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


Sponsored Ads