Hi-- I recently finished editing four books and am now back to updating the OpenSolaris style guide with the changes from the August 2006 version of the Sun Editorial Style Guide.
I have finished incorporating the changes into chapters 2 and 3 of the OpenSolaris style guide. These changes necessitated the addition of a new chapter, Chapter 9, "Structuring Information." Note that to avoid confusion with the new chapter, I intend to reword the title of Chapter 8, "Structure of Documents," to "Types of Documents." 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 April 30. 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 provide details. The updated chapters and the new chapter include: * New guidelines * Clarification of existing guidelines * More examples * Bug fixes and consistency improvements The most significant change was to move general writing guidelines from the previous version of Chapter 3, "Online Writing Style," to appropriate locations in Chapter 2, "Writing Style," and to the new chapter, "Structuring Information." "General" writing guidelines are applicable to both print and online documents. You will see that the movement of these general writing guidelines has created a lot of change tracking. I hope you can follow all the changes without too much trouble. I've added Writer Remarks to assist you. Some of the specific changes include the following: * Chapter 2: Moved "Learn to Improve Your Style" and "Work With an Editor" sections towards the beginning of the chapter to improve the content flow. * Chapter 2: Deleted "Write Concise Paragraphs" section and moved a concise version of the example in that section to Example 2-2, "Keeping Paragraphs Short." * Chapter 2: Moved "Constructing Scannable Paragraphs, Headings, and Lists" section from Chapter 3 to Chapter 2. Note that this section was moved in its entirely and all the changes to the section are change tracked in Chapter 2. * Chapter 2: Added new table of common anthropomorphic phrases that provides suggested alternatives and examples. Also clarified guidelines about anthropomorphisms. * Chapter 2: Added new table of common idioms and colloquialisms that provides suggested alternatives and examples. * Chapter 2: Added acceptable phrasal verbs (for example, "set up") and new table of phrasal verbs to avoid. * Chapter 3: Moved general writing guidelines to Chapter 2, "Writing Style." * Chapter 3: Moved the sections on each type of structure to Chapter 9, "Structuring Information." * Chapter 3: Moved most of the content in the original "Writing Short, Self-Contained Topics" section (now called "Writing Online Topics") to Chapter 9, "Structuring Information." * Chapter 3: Moved most of the content in the original "Constructing Scannable Paragraphs, Headings, and Lists" section (now called "Constructing Scannable Text in Online Documents") to Chapter 2, "Writing Style." * Chapter 3: Removed the following sections because they are redundant with other material covered in the OpenSolaris style guide: "Write Meaningful Headings and Subheadings," "Use Bulleted Lists," and "Use Jump Lists." * Chapter 3: Removed recommendation to use bold for key words and phrases. * Chapter 9: Created this new chapter, which is derived from the previous version of Chapter 3, "Online Writing Style." * Chapter 9: Replaced the "Organizing by Table" example with a better example. * Chapter 9: Deleted the second "Organizing by Flow Diagram" example because it presents a format this is unlikely to be used. Thanks so much for your help! Alysson -- Alysson Troffer Technical Editor Sun Microsystems, Inc. This message posted from opensolaris.org
