Hi all,
This is the beta review of the OpenSolaris Style Guide TOC. Please
review the outline below with focus on errors (topics we should not
include) and omissions (additional topics you want to include).
Comments, questions, and feedback on the table of contents should be
provided by next Friday, Nov. 11th. If this is not enough time, let me
know.
Please email comments to the alias so that we can efficiently capture
and address any conflicting or common additions and suggestions.
Proposal: OpenSolaris Style Guide
Table of Contents
__________________________________
Preface
About This Guide
How This Book Is Organized
Who Should Read This Guide
Associated Documentation
Related Documentation
Reference Sources
1. Constructing Text
Headings
-Writing Section headings
-Capitalizing and Punctuating Headings
Lists
-Capitalizing and Punctuating Lists
-Writing Bulleted Lists
-Writing Numbered Lists
-Writing Jump Lists
Tables
-Determining the Type of table to Use
-Writing Table Introductions
-Writing Table Column Headings
-Writing Table Text
Code Examples
-Writing Code Examples
Man Page References
-Writing Man Page References
Error Messages
-Documenting Error Messages
Cross-References
-Writing Cross-References
Notes, Cautions, and Tips
-Writing Notes
-Writing Cautions
-Writing Tips
Illustrations
-Types of Illustrations
-Placing Illustrations
-Writing Captions for Illustrations
2. Technical Documentation Concepts
Stylistic Principles
-Write Simply, Directly, and Accurately
-Be Consistent
-Avoid Jargon
-Write Concise Paragraphs
Online Writing Style
-Creating an Effective Document Structure
-Writing Short, Self-Contained Topics
-Constructing Scannable Paragraphs, Headings, and Lists
Write for the Reader
-Make Decisions for the Reader
-Anticipate Questions
Avoid Style That Could Offend the Reader
-Use Acceptable Methods to Achieve Common Gender
-Do Not Talk Down to the Reader
Common Writing Problems to Avoid
-Commands as verbs
-Redundancies
Structure of Documents
-Descriptions of the Parts of a Document
-Title Page
-Legal Notice
-Table of Contents
-Preface
-Chapters
-Appendixes
-Index
-Revision History
-Types of Software Manuals
-Installation Guides
-Programmer's Guides
-System Administration Guides
-User's Guides
-API Documentation
-Other Product Documents
-White Papers
-Online Help
-Man Pages
-Release Notes
-Student and Instructor Guides
-Web-Based Training
4. Writing for an International Audience
Guidelines for Writing for Translation
-Include International Date, Time, and Contact Information
-Avoid Informal Language and Styles
-Avoid Abbreviations, Acronyms, and Contractions
-Use Words Precisely
-Limit the Use of Pronouns
-Simplify Sentences
5. Checking and Reviewing Your Document
Reviews
-Developmental Editing
-Copy Editing
-Proofreading
Checks You Can Do Yourself
-Copy Editing Checklist
-Proofreading Checklist
6. Indexing Your Documentation
Creating an Index
-When an Index is Needed
-Selecting topics to Index
-Describing a Topic
-Double-Posting
-Avoiding Indexing Problems
Refining and Checking an Index
-Spelling
-Differences in Wording
-Misused Singular Forms and Plural Forms
-Number of Page References for Entries
-Secondary Entries
7. Glossary Guidelines
Glossary Content
-Finding Definitions
-Creating New Terms
-Formatting a Glossary
Writing Good Glossary Entries
-Defining a Term
-Defining Multiword Terms
-Defining Parts of Speech
-Creating Multiple Definitions
-Defining Acronyms and Abbreviations
8. Legal Guidelines
Legal Requirements Checklist
-Third-Party Trademarks
-Third-Party Web Site References
-Software Compatibility
-Examples in Documentation
OpenSolaris License Agreement CDDL
-General CDDL Information
Copyrights and Trademark Attributions
-Third-Party Copyrighted Information
-Trademark Terms
-Third-Party Copyrighted Information
9. Writing Alternative Text for Nontext Elements
General Guidelines for Writing Alternative Text
-Writing Short Alternative Text
-Writing Long Alternative Text
Writing About Nontext Elements
-Icons
-Graphics
-Diagrams
10. Writing for the Solbook DTD
General Guidelines for Writing to the Solbook DTD
-Introduction to SGML
-Attributes and Entities
-Components of a Book
-Block Elements
-Inline Elements
-Cross-References and Links
-Tables
-Graphics and Multimedia
-Error Messages and Question Lists
-Building an Index
A. General Word Usage
-Correct Term Usage and Style
B. OSSG Contributors
-Sun Editorial Forum
Thanks,
Michelle
OpenSolaris Doc Dommunity
This message posted from opensolaris.org
