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.
Subject:Summary: Documenting uncertain features From:Jon Herrera <jonherrera -at- YAHOO -dot- COM> Date:Tue, 13 Oct 1998 16:13:01 -0700
Many thanks to Connie Fabian-Isaacs, Rowena Hart, Tim Altom, Beth
Kane, Chris Hamilton, Tom Johnson, William Swallow, Leonard Porrello,
Jody Lorig, Karen Byers, and Bethany Haara for their responses.
The most suggested option is to use FrameMaker's conditional text
feature to distinguish the uncertain features from the rest of the
text. This will allow easy showing and hiding of specific text.
Other suggestions include:
* Saving the additional/future release features in a separate file.
* Greying out text and including a style reference in the About
Help section explaining that these features are unavailable.
* Adding topic titles and bookmarks, but noting in the text that
these features are unavailable in the current release.
* Avoid doing any xrefs until the last moment
* Make a chart of all sections, with notations of "certain" and "maybe"
* Make sure you have enough space at the back end of the project to
assemble the actually-used sections and make xrefs
* Document your progress so when you're being screamed at towards the
shipping date, you can calmly point out that loose specs produce lots of
wasted time.
* Make sure you have a solid, unbreakable structure for the
manual. This will make the removal/addition of sections smoother. Make
the
manual into modules that can be unplugged without crashing the whole
structure.
This requires extensive planning to pull off.
* Don't fully document a product until such decisions have already
been made, AND everything you're documenting is in a working interface
that you can test
yourself.
* You could document the vapor-pieces in a separate doc and plug them
in
later, adding cross-refs as you go, if they decide they will implement
them. Until they make a decision I wouldn't give them anything with the
vapor-pieces in it except an outline, such as a TOC.
* As a rule, I don't document the uncertain. Wait on those
items until they have been decided on.
* The cleanest way I can think of to set something aside as temporary
is to create a paragraph style that puts the text in a different color
(I like to use red because it prints black on printouts but is easy to
see when scanning the document on the screen). Most DTPs can search on
color, so finding items that need attention are easy to find. One
caveat, make sure nobody that is going to view this to find
corrections is colorblind for the color you select.
* The last company I worked for asked that I include a Future Possible
Enhancement sections to some documents. That was the place that all
those temporary/vague/maybe/nice-to-have features got dropped.
* My company will usually, send a Release note or Addendum with the
products if any features were added that didn't make into the manual. If
certain features will definitely be in the product, place those
features in the manual.
_________________________________________________________
DO YOU YAHOO!?
Get your free @yahoo.com address at http://mail.yahoo.com
