TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
-----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?
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.
