Developing quality technical information : a handbook for writers and editors
"The examples are excellent--right on target and easy to understand and adapt. Even those who don't adopt the entire procedure can profit from the parts, but the greatest value will flow to those who adopt the whole." --Carolyn Mulford, senior writer and editor of Writing That Works &...
| Autor Corporativo: | |
|---|---|
| Otros Autores: | , |
| Formato: | Libro electrónico |
| Idioma: | Inglés |
| Publicado: |
[Place of publication not identified]
Prentice Hall Professional Technical Reference
2004
|
| Edición: | 2nd edition |
| Colección: | IBM Press series--information management
|
| Materias: | |
| Ver en Biblioteca Universitat Ramon Llull: | https://discovery.url.edu/permalink/34CSUC_URL/1im36ta/alma991009627458106719 |
Tabla de Contenidos:
- Cover
- Contents
- Contents
- Welcome
- Is this book for you?
- How to use this book
- Conventions used in this book
- Changes in this edition
- Acknowledgments
- Chapter 1. Quality technical information
- What is quality technical information?
- Relationships among the quality characteristics
- Order of the groups
- Quality characteristics compared with elements and guidelines
- Other possible quality characteristics of technical information
- Using the quality characteristics to develop quality technical information
- Preparing to write: understanding users, tasks, and the product
- Writing and rewriting
- Reviewing, testing, and evaluating technical information
- Writing task, concept, and reference topics
- Establishing a unit of reuse
- Restructuring technical information
- Part 1. Easy to use
- Chapter 2. Task orientation
- Write for the intended audience
- Present information from the user's point of view
- Indicate a practical reason for information
- Focus on real tasks, not product functions
- Use headings that reveal the tasks
- Divide tasks into discrete subtasks
- Provide clear, step-by-step instructions
- In sum
- Chapter 3. Accuracy
- Write information only when you understand it, and then verify it
- Keep up with technical changes
- Maintain consistency of all information about a subject
- Use tools that automate checking for accuracy
- Check the accuracy of references to related information
- In sum
- Chapter 4. Completeness
- Cover all topics that support users' tasks, and only those topics
- Cover each topic in just as much detail as users need
- Use patterns of information to ensure proper coverage
- Repeat information only when users will benefit from it
- In sum
- Part 2. Easy to understand
- Chapter 5. Clarity
- Focus on the meaning
- Avoid ambiguity
- Keep elements short.
- Write cohesively
- Present similar information in a similar way
- Use technical terms only if they are necessary and appropriate
- Define each term that is new to the intended audience
- In sum
- Chapter 6. Concreteness
- Choose examples that are appropriate for the audience and subject
- Use focused, realistic, accurate, up-to-date examples
- Make examples easy to find
- Make code examples easy to adapt
- Use scenarios to illustrate tasks and to provide overviews
- Set the context for examples and scenarios
- Relate unfamiliar information to familiar information
- Use general language appropriately
- In sum
- Chapter 7. Style
- Use correct grammar
- Use correct and consistent spelling
- Use consistent and appropriate punctuation
- Write with the appropriate tone
- Use an active style
- Use the appropriate mood
- Follow template designs and use boilerplate text
- Create and follow style guidelines
- In sum
- Part 3. Easy to find
- Chapter 8. Organization
- Organize information into discrete topics by type
- Organize tasks by order of use
- Organize topics for quick retrieval
- Separate contextual information from other types of information
- Organize information consistently
- Provide an appropriate number of subentries for each branch
- Emphasize main points
- subordinate secondary points
- Reveal how the pieces fit together
- In sum
- Chapter 9. Retrievability
- Facilitate navigation and search
- Provide a complete and consistent index
- Use an appropriate level of detail in the table of contents
- Provide helpful entry points
- Link appropriately
- Design helpful links
- Make linked-to information easy to find in the target topic
- In sum
- Chapter 10. Visual effectiveness
- Use graphics that are meaningful and appropriate
- Choose graphics that complement the text
- Use visual elements for emphasis.
- Use visual elements logically and consistently
- Balance the number and placement of visual elements
- Use visual cues to help users find what they need
- Ensure that textual elements are legible
- Use color and shading discreetly and appropriately
- Ensure that all users can access the information
- In sum
- Part 4. Putting it all together
- Chapter 11. Applying more than one quality characteristic
- Applying quality characteristics to task information
- Applying quality characteristics to conceptual information
- Applying quality characteristics to reference information
- Applying quality characteristics to information for an international audience
- Applying quality characteristics to information on the Web
- Revising technical information
- Chapter 12. Reviewing, testing, and evaluating technical information
- Inspecting technical information
- Testing information for usability
- Testing technical information
- Editing and evaluating technical information
- Reviewing the visual elements
- Part 5. Appendixes
- Appendix A. Quality checklist
- Appendix B. Who checks which quality characteristics?
- Appendix C. Quality characteristics and elements
- Looking at the quality characteristics
- Looking at the elements
- Resources and references
- Easy to use
- Easy to understand
- Easy to find
- Putting it all together
- Glossary.
