Read Me First! A Style Guide for the Computer Industry

This fully revised second edition reflects dramatic changes in the production and delivery of technical documentation. Coverage includes: Detailed grammar, punctuation, typographic, and legal guidelines Extensive guidance on creating effective step-by-step procedures Techniques for documenting Web applications and graphical user interfaces Expert help with creating indexes and glossaries Extensive recommendations for using hyperlinks Checklists and forms for editing, tracking manuscripts, and verifying production status Guidelines for using commonly confused words and terms Practical tips for gender-neutral writing Internationalization guidelines that simplify translation and improve clarity for non-native English speakers Real-world help for managers: hiring writers, working with illustrators, managing schedules and workflow, coordinating with printers, and more Expanded and updated recommended reading listThe must-have reference for every technical writer, editor, and documentation manager-now 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:- Detailed grammar, punctuation, typographic, and legal guidelines- Extensive guidance on creating effective step-by-step procedures- Techniques for documenting Web applications and graphical user interfaces- Expert help with creating indexes and glossaries- Extensive recommendations for using hyperlinks- Checklists and forms for editing, tracking manuscripts, and verifying production status- Guidelines for using commonly confused words and terms- Practical tips for gender-neutral writing- Internationalization guidelines that simplify translation and improve clarity for non-native English speakers- Real-world help for managers: hiring writers, working with illustrators, managing schedules and workflow, coordinating with printers, and more- Expanded and updated recommended reading listA guide to creating technical documentation, this covers everything from grammar to clarity, illustrations to workflow. This second edition reflects changes in the production and delivery of technical documentation.Preface How This Book Is Organized 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 to these 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 facilitates effective communication. Chapter 4, "Online Writing Style," provides guidelines for writing documentation that is intended primarily for online presentation. Some of these guidelines also apply to online help and web pages. Chapter 5, "Constructing Links," provides guidelines for using links effectively in online 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 writing material that is easily understood by readers whose first language is not English and that 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 up a manual and lists the order in which they appear. This chapter also describes typical types of computer documentation. Chapter 10, "Working With an Editor," explains how writers and editors work together to produce high-quality documents. Chapter 11, "Working With Illustrations," describes illustration formats, styles, and types. 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 document graphical user interfaces (GUIs). This chapter also provides specific guidelines for writing about web pages and referencing URLs. Chapter 13, "Glossary Guidelines," explains how to create a glossary for a technical manual. Chapter 14, "Indexing," explains how to prepare an index for a technical manual. This chapter 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 about issues 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 you can use at various stages of documentation development, including art tracking, print authorization, and a technical review cover letter. Appendix C, "Correct Usage of Terms," provides alternatives for terms that you should not use in technical documentation, and terms that you should avoid. This appendix also provides some guidance related to commonly confused words and terms. Appendix D, "Recommended Reading," presents a list of books, divided by subject headings, 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 has increased, and online delivery has become a fast-growing means of delivery for technical documentation. Read Me First!has been extensively revised in response to these changes. The highlights of this revision are as follows: A more logical organization of chapters Addition of a chapter on online writing style Addition of a chapter on constructing links Addition of a chapter on writing tasks, procedures, and stepsREAD ME FIRST! is the definitive guide to creating technical documentation that is clear, consistent, and easy to understand. Sun Microsystems' award-winning tech writers and editors cover everything from grammar to clarity, illustrations to workflow. This fully revised Second Edition reflects dramatic changes in the technology industries, with extensive new coverage of Web/online documentation, internationalization, and much more.bull; bull;The must-have reference for every technical writer, editor, and documentation manager bull;Provides all the information you need to document hardware, software, or other computer products bull;Written by award-winning documentation experts at Sun Technical Publications, Read Me First! is the most comprehensive guide to creating documentation that is clear, consistent, and easy to understand& bull; The must-have reference for every technical writer, editor, and documentation manager & lt;br/ & gt; & bull; Provides all the information you need to document hardware, software, or other computer products & lt;br/ & gt; & bull; Written by award-winning documentation experts at Sun Technical Publications, Read Me First! is the most comprehensive guide to creating documentation that is clear, consistent, and easy to understand