The must-have reference for every technical writer, editor, and documentation managernow fully updated!
Read Me First! is the definitive guide to creating technical documentation that is clear, consistent, and easy to understand. Sun Microsystems' award-winning technical writers and editors cover everything from grammar to clarity, illustrations to workflow. This fully revised second edition reflects dramatic changes in the production and delivery of technical documentation. Coverage includes:
Download the Sample Chapter related to this title.
1. Mechanics of Writing.
Capitalization. Contractions. Gerunds and Participles. Numbers and Numerals. Pronouns. Technical Abbreviations, Acronyms, and Units of Measurement. Punctuation.
Headings. Lists. Tables. Code Examples. Error Messages. Cross-References. Endnotes, Footnotes, and Bibliographies. Notes, Cautions, and Tips. Part Dividers. Typographic Conventions. Key Name Conventions.
Why Is Style Important? Stylistic Principles. Some Basic Elements of Style. Writing for the Reader. Style That Could Offend the Reader. Common Writing Problems to Avoid. Ways to Improve Your Style.
About These Guidelines. Solving Online Writing Problems. Creating an Effective Document Structure. Writing Short, Self-Contained Topics. Constructing Scannable Paragraphs, Headings, and Lists. Preserving Context in Online Documents.
About These Guidelines. Where to Place Links. General Linking Strategies. Guidelines for Writing Link Text.
Understanding the Relationship Among Tasks, Procedures, and Steps. Developing Task Information. Writing Procedures. Writing Steps.
General Guidelines for Writing for Translation. Cultural and Geographic Sensitivity. Definitions and Word Choice. Grammar and Word Usage. Numbers, Symbols, and Punctuation. Illustrations and Screen Captures.
Copyrights. Trademarks. Third-Party Web Site References. Protection of Proprietary/Confidential Information.
What Is a Documentation Set? Documentation Plans. Document Plan. Abstracts. Structure of Manuals. Descriptions of the Manual Parts. Types of Hardware Manuals. Types of Software Manuals. Other Product Documents. Training Documents.
Technical Editor's Role. Editor's Role in Producing Online Documents. Types of Editing. Edit Schedules. Document Submission. Editing Marks. Edit Style Sheet.
Working With an Illustrator. Illustration Formats, Styles, and Types. Examples of Illustrations. Placing Illustrations. Writing Captions for Illustrations. Writing Callouts for Illustrations. Creating Quality Screen Captures. Creating Leader Lines. Simplifying Online Illustrations.
Using GUI Terminology. Writing About Windows, Dialog Boxes, and Menus. Writing About the Web.
Glossary Content. Terms for an International Audience. When to Include a Glossary. Writing Good Glossary Entries.
What Is an Index? Style and Format. Creating an Index. Refining and Checking an Index. Bad Page and Column Breaks. Checking the Size of the Index. Global Index. Online Index.
Establishment of a Publications Department. Scheduling. Documentation Process. Internationalization and Localization. Online Documentation Considerations. Final Print Production. Post-Production Considerations.
Manuscript Tracking Chart. Request for Editing Form. Artwork Request Form. Technical Review Cover Letter. Authorization to Produce Document. Print Specification.
Desktop Publishing and Document Design. Editing Standards. Graphics and Illustration. HTML and XML. Indexing. Information Mapping. Internationalization and Localization. Legal Issues. Online Help. Online Writing Style. Platform Style Guides. Printing. Project Management. Reference Works. Standard Generalized Markup Language (SGML). Typography. Usability Testing. User Interfaces. Web and Internet Publishing. Writing Standards. Writing Standards for Technical Writing.
Read Me First! is organized as described in the following paragraphs.
Chapter 1, "Mechanics of Writing," reviews basic punctuation rules and guidelines,plus other general writing rules and conventions. This chapter also notes exceptions tothese rules, guidelines, and conventions.
Chapter 2, "Constructing Text," provides guidelines for tables, cross-references,headings, lists, and other text elements.
Chapter 3, "Writing Style," provides guidelines for writing in a style that facilitateseffective communication.
Chapter 4, "Online Writing Style," provides guidelines for writing documentation thatis intended primarily for online presentation. Some of these guidelines also apply toonline help and web pages.
Chapter 5, "Constructing Links," provides guidelines for using links effectively inonline documents.
Chapter 6, "Writing Tasks, Procedures, and Steps," provides guidelines for writing tasks, procedures, and steps in a procedure.
Chapter 7, "Writing for an International Audience," provides guidelines for writingmaterial that is easily understood by readers whose first language is not English andthat can be easily translated into other languages.
Chapter 8, "Legal Guidelines," provides guidelines for the proper use of copyrights,trademarks, and proprietary information.
Chapter 9, "Types of Technical Documents," describes the various parts that make upa manual and lists the order in which they appear. This chapter also describes typicaltypes of computer documentation.
Chapter 10, "Working With an Editor," explains how writers and editors worktogether to produce high-quality documents.
Chapter 11, "Working With Illustrations," describes illustration formats, styles, andtypes. This chapter also provides guidelines for writing callouts, arranging callouts,using leader lines, and writing captions.
Chapter 12, "Writing About Graphical User Interfaces," explains how to documentgraphical user interfaces (GUIs). This chapter also provides specific guidelines forwriting about web pages and referencing URLs.
Chapter 13, "Glossary Guidelines," explains how to create a glossary for a technicalmanual.
Chapter 14, "Indexing," explains how to prepare an index for a technical manual. Thischapter covers issues such as selecting topics to index, style rules for creating an index,and editing the index.
Appendix A, "Developing a Publications Department," provides information aboutissues related to a documentation department, including topics such as scheduling,roles and responsibilities, technical review, and printing and production.
Appendix B, "Checklists and Forms," contains sample checklists and forms that youcan use at various stages of documentation development, including art tracking, printauthorization, and a technical review cover letter.
Appendix C, "Correct Usage of Terms," provides alternatives for terms that youshould not use in technical documentation, and terms that you should avoid. Thisappendix also provides some guidance related to commonly confused words andterms.
Appendix D, "Recommended Reading," presents a list of books, divided by subjectheadings, that you might want to consult for additional information.Changes for This Revision
Since the last revision of Read Me First!, the globalization of technical products hasincreased, and online delivery has become a fast-growing means of delivery fortechnical documentation. Read Me First! has been extensively revised in response tothese changes. The highlights of this revision are as follows:
Download the Index
file related to this title.