Hi-- I have finished incorporating the changes into Chapter 5, "Writing Tasks, Procedures, and Steps," in the OpenSolaris style guide. The changes are fairly extensive.
If you have the time and the inclination, please review the changes, which are marked with change tracking. Any feedback is welcome. To access the chapter, go to: http://opensolaris.org/os/community/documentation/reviews/ I'd appreciate receiving your feedback by August 13. Hopefully, this three-week deadline will give you plenty of time. I'll summarize the changes here. If you would like to know more about why a specific change was made, feel free to ask. I'd be happy to answer. The updated chapter includes: * New guidelines * Clarification of existing guidelines * More examples * Bug fixes and consistency improvements Some of the specific changes include the following: * Refined definition of "task" * Enhanced "Including Prerequisites" section * Clarified when to use continuous prose for tasks * Added section on presenting command explanations * Added guideline about establishing the entire context in which a procedure is done * Removed recommendation to try to write no more than five steps for a procedure presented in an online document * Added guideline about not providing a detailed description of each window, menu, or field in an interface * Added guidelines for the use of illustrations in procedures * Clarified guidelines about documenting a procedure when the procedure can be performed either through a GUI or the command line * Added guidelines about writing steps in procedures, including how to present information in a logical order and how to ensure that steps are included for all actions the user must perform * Clarified guidelines for writing steps for GUI procedures * Added guideline about not using "or" to indicate branching in steps * Promoted the "Checking for Structural Problems" section from a level-two section to a level-one section * Added section on how to present repeated steps in a procedure * Refined the index Thanks so much for your help! Alysson -- Alysson Troffer Technical Editor Sun Microsystems, Inc. This message posted from opensolaris.org
