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.
Based on your post, it sounds like your management has some halfway
decent ideas about what kind of docs they need, but they are
micro-managing you a bit. Their requests sound a bit
off-the-top-of-their-heads. If you can, ask them to step back a bit and
help them identify the information needs they are trying to solve with
each of these docs.
Getting Started Guide - well, nothing wrong with that. It's a
nice-to-have. If you already have a good user guide and admin guide in
place, a Getting Started guide can be created pretty easily. As far as
level of detail, let it be more or less a subset of the user guide.
Don't include concepts or facts that aren't also in the user guide.
Don't make the mistake of trying to write the Getting Started guide
first.
Troubleshooting Guide - Another nice-to-have, maybe as an appendix in
an Admin Guide. First, make a list of troubles, then write the
solutions. If nobody has experienced the problem, should it really be
in a troubleshooting guide? Don't think up exotic troubles just to
write a troubleshooting guide. Keep it simple with basic things like
"Can't connect" or "Won't start." Also see the previous threads about
documenting-by-FAQ - usually these FAQs tend to be NBAQs (Never Been
Asked Questions).
Use Cases book - Unless your product is a modeling tool that creates
Use Cases, this is an odd request. I'd challenge them on this. It may
be that they want task-based documentation but are not knowledgeable
enough about tech writing to express this requirement - you can help
them refine this idea. I wouldn't imagine that a user manual written as
use cases would be very helpful.
ini file guide - Start by documenting the .ini file with inline
comments. Any additional thoughts on an .ini file probably belong in an
administration or installation guide. A standalone ".ini file guide"
sounds a little odd. Yes, you do need to document everything in the
.ini file even if they aren't allowed to edit it. Otherwise they will
edit it to find out what happens (well, that's what *I* would do!).
Also, what is an "ini file command?" And, why does a database product
have an ini file? Usually this info moves to the database in Version
1.1 - ask your dev team.
Mike O.
__________________________________
Do you Yahoo!?
Yahoo! Mail - now with 250MB free storage. Learn more. http://info.mail.yahoo.com/mail_250
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.
