Writing and Editing Modular Documentation: Some Best Practices
description
Transcript of Writing and Editing Modular Documentation: Some Best Practices
![Page 1: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/1.jpg)
Writing and Editing Modular Documentation: Some Best PracticesYoel Strimling (Comverse)
Based on a joint presentation with Michelle Corbin (IBM) at the 55th Annual STC Technical Communication Summit, Philadelphia (May 2008)
![Page 2: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/2.jpg)
2
The Mechanics of Modular Documentation
Some Best Practices for Writing and Editing Modular Documentation
The Editor’s Role in Creating Modular Documentation
![Page 3: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/3.jpg)
The Mechanics of Modular Documentation
![Page 4: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/4.jpg)
4
The Mechanics of Modular Documentation Modularization is the act of splitting text
into discrete, standalone units of information, called topics.
Writing in a modular way helps writers better organize, construct, and write their documentation.
Writing in a modular way helps readers better find, use, and follow what is written.
Writing in a modular way makes information:
Easier to find Easier to understand Easier to use
![Page 5: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/5.jpg)
5
Principles to Remember
Labeling
Linking
Chunking
The logic behind modular documentation is quite straightforward – just remember three simple principles:
![Page 6: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/6.jpg)
6
Chunking
Information must be categorized into logical, independent, standalone topics based on content type – concept, task, or reference.
![Page 7: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/7.jpg)
7
Labeling
Topic titles must be unique, clear, accurate, and meaningful, with each topic type having its own specific heading syntax.
![Page 8: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/8.jpg)
8
Linking
Topics must be connected to other related or relevant topics so readers can easily find the information they need.
![Page 9: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/9.jpg)
9
The Three Topic Types
Provide background information that readers need to know, and explain or describe concepts in a descriptive format
Provide sequential step-by-step instructions in a procedural format
Provide detailed explanatory information in a structured lookup table or list format
Concept Topics
Task Topics
Reference Topics
![Page 10: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/10.jpg)
Some Best Practices for Writing and Editing Modular Documentation
![Page 11: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/11.jpg)
11
Some Best Practices for Writing and
Editing Modular Documentation Topic types must not be mixed (Chunking) Topics must be standalone (Chunking) Titles
must be unique and descriptive (Labeling) Related topic links must be meaningful (Link
ing) Topic collections must be meaningful and
user-focused (all three)
![Page 12: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/12.jpg)
12
Topic Types Must Not Be Mixed
Focus on separating descriptive information (concept and reference topics) from task-oriented information (task topics).
Keep the information clear and to the point.
![Page 13: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/13.jpg)
13
Before…
![Page 14: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/14.jpg)
14
… and After (Concept Topic)
![Page 15: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/15.jpg)
15
… and After (Task Topic)
![Page 16: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/16.jpg)
16
Topics Must Be Standalone
Readers should be able to read one section without having to read another.
Do not assume that readers read something you wrote previously.
![Page 17: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/17.jpg)
17
Example
![Page 18: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/18.jpg)
18
Titles Must Be Unique and Descriptive Topic titles must be unique, clear,
concise, and descriptive, correctly identifying the content included in a topic.
Topic titles provide immediate visual clues to readers, enabling them to easily locate, understand, and use the information they need.
![Page 19: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/19.jpg)
19
Before…
![Page 20: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/20.jpg)
20
… and After (Concept Topic)
![Page 21: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/21.jpg)
21
… and After (Task Topic)
![Page 22: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/22.jpg)
22
Related Topic Links Must Be Meaningful The more complex the document or the
information is, the more critical it becomes to provide readers with a way to successfully navigate between different topics.
Linking enables readers to easily navigate between related subject matter in a document and find the information they need.
![Page 23: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/23.jpg)
23
Example (Concept Topic)
![Page 24: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/24.jpg)
24
Example (Task Topic)
![Page 25: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/25.jpg)
25
Topic Collections Must Be Meaningful and User-Focused There must be an information hierarchy
or “story” that connects the topics in your document.
Sometimes you need to force readers to read sequentially, even in modular documentation (for example, procedures that must be done in a particular order).
![Page 26: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/26.jpg)
26
Example
![Page 27: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/27.jpg)
The Editor’s Role in Creating Modular Documentation
![Page 28: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/28.jpg)
28
The Editor’s Role in Creating Modular Documentation Expert Educator User Advocate (“First Reader”)
![Page 29: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/29.jpg)
29
Editor As Expert
Information models Usability research Templates and style guides
![Page 30: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/30.jpg)
30
Editor As Educator
Continuous education Implementation-level education Frequent consultations with writers
![Page 31: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/31.jpg)
31
Editor As User Advocate
Edit for one voice, consistency across writers
Edit “in context” as user will see it Edit for usability, not reusability
![Page 32: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/32.jpg)
32
Summary
Writing and editing modular documentation is similar to, and yet different from, writing and editing linear documentation.
Writers and editors must learn more about information models to ensure topics are chunked properly, labeled correctly, and linked appropriately.
Editors must become experts and educators, working collaboratively with architects and writers.
In modular documentation, our role as reader advocate is even more critical than in linear documentation.
![Page 33: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/33.jpg)
33
Any Questions?
![Page 34: Writing and Editing Modular Documentation: Some Best Practices](https://reader035.fdocuments.net/reader035/viewer/2022081507/568163e7550346895dd54e96/html5/thumbnails/34.jpg)
34
For More Details…
The full text of this paper can be found at the Writers UA site:http://www.writersua.com/articles/modular/index.html
An abridged version can be found in the May 2009 issue of Intercom.