1. #tcworldIndia2019
Writing and Editing Modular Documentation: Some Best Practices Based on a previous joint presentation with Michelle Corbin (IBM)
Yoel Strimling

2. Our Goal
To create and deliver high-quality documentation that meets our readers’ needs and expectations

3. How Do Readers Define High-Quality Documentation?
Accurate
The information in the documentation is correct, reliable, and free of error.
Relevant
The information in the documentation is applicable and helpful for the task at hand.
Clear
The information in the documentation is easy to read and understand.
Accessible
Readers can easily find the information they need to know or do.

4. In Other Words… High-quality documentation must be: Intrinsically good
Contextually appropriate for the need
Clearly represented
Accessible to the reader

5. What Are We Going to Learn?
The mechanics of modular documentation
Our role in creating modular documentation
Some best practices for writing and editing modular documentation

6. 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

7. Principles to Remember
The logic behind modular documentation is quite straightforward – just remember three simple principles:
Chunking
Labeling
Linking

8. What Is Chunking?
Information must be categorized into logical, independent, standalone topics based on content type – concept, task, or reference.

9. Editing Modular Documentation: Some Best Practices
June 4, 2008
The Three Topic Types
Concept Topics
Provide background information that readers need to know, and explain or describe concepts in a descriptive format
Task Topics
Provide sequential step-by-step instructions in a procedural format
Reference Topics
Provide detailed explanatory information in a structured lookup table or list format

10. What Is Labeling?
Topic titles must be unique, clear, accurate, and meaningful, with each topic type having its own specific heading syntax.

11. What Is Linking?
Topics must be connected to other related or relevant topics so readers can easily find the information they need.

12. What Are We Going to Learn?
The mechanics of modular documentation
Our role in creating modular documentation

13. We are all editors!

14. Our Role in Creating Modular Documentation
We are reader advocates (the “first reader”)!
We are experts!
We are educators!

15. We Are Reader Advocates (the “First Reader”)!
We are first and foremost reader advocates – we must review the documentation for usability, not reusability.

16. We Are Experts!
We are documentation quality experts – we must learn the rationale behind modular documentation and how to apply it.

17. We Are Educators!
We are teachers – we must help others understand the best way to create high- quality documentation that makes readers happy.

18. What Are We Going to Learn?
The mechanics of modular documentation
Our role in creating modular documentation
Some best practices for writing and editing modular documentation

19. Some Best Practices for Writing and Editing Modular Documentation
Topic types must not be mixed (Chunking)
Topics must be standalone (Chunking and Linking)
Titles must be unique and descriptive (Labeling)
Related topic links must be meaningful (Linking)
Topic collections must be meaningful and reader-focused (all three)

20. 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.

21. Before…

22. … and After (Concept Topic)

23. … and After (Task Topic)

24. Some Best Practices for Writing and Editing Modular Documentation
Topic types must not be mixed (Chunking)
Topics must be standalone (Chunking and Linking)

25. Topics Must Be Standalone
Readers should be able to read one section without having to read another.
Do not assume that readers read something that was written previously.

26. Example (Task Topic)

27. Some Best Practices for Writing and Editing Modular Documentation
Topic types must not be mixed (Chunking)
Topics must be standalone (Chunking and Linking)
Titles must be unique and descriptive (Labeling)

28. 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.

29. Before…

30. … and After (Concept Topic)

31. … and After (Task Topic)

32. Some Best Practices for Writing and Editing Modular Documentation
Topic types must not be mixed (Chunking)
Topics must be standalone (Chunking and Linking)
Titles must be unique and descriptive (Labeling)
Related topic links must be meaningful (Linking)

33. 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.

34. Two Types of Links Integrated Cross-References Related Links
Necessary and relevant links to other topics directly discussed in the text of the current topic.
Integrated into the text itself in a logical manner, either in parentheses at the end of the sentence where they are mentioned (but before the period), in a separate sentence, or in a bulleted list.
Related Links
Necessary and relevant links to other topics that are not directly discussed in the current topic’s text.
These two are mutually exclusive, that is, if you link to a topic as an integrated cross-reference, do not put it as a related link as well; if you link to a topic as a related link, do not integrate it into the text as a cross-reference.
Parent Topics:
Links to the topic immediately above the current one in the hierarchy (that is, a child topic to its parent topic)
Enables readers to go up a level to either get broader information or to navigate to other topics included in the higher topic.
Related Tasks/Information:
Links to at least all children of the current topic (unless they are integrated cross-references) as well as to other appropriate related topics in the document (regardless of their position in the hierarchy)
Related Tasks: For task topics
Related Information: For concept and reference topic

35. Example (Concept Topic)

36. Example (Task Topic)

37. Some Best Practices for Writing and Editing Modular Documentation
Topic types must not be mixed (Chunking)
Topics must be standalone (Chunking and Linking)
Titles must be unique and descriptive (Labeling)
Related topic links must be meaningful (Linking)
Topic collections must be meaningful and reader-focused (all three)

38. Topic Collections Must Be Meaningful and Reader-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 or in a very long task).

39. Before... (Task Topic)

40. ... and After (Task Topics)
Backing Up the DSU Manually
This procedure describes how to manually back up the DSU. It is made up of the following sequence of procedures:
Backing Up the Oracle Database to Disk
Checking the Completeness of the Oracle Database Backup to Disk
Setting Up the LTO2 Tape to Save the DSU Data
Backing Up the DSU to the LTO2 Tape

41. Backing Up the Oracle Database to Disk
This procedure describes how to backup the Oracle database to disk using RMAN, which is the first step in Backing Up the DSU Manually.
What You Need
Access to a DSU unit
How
Log in to the DSU database server as user root.
Change to user oracle by typing:
su -oracle
At the command prompt, type:
crontab -l | grep -i backup_db.ksh
The backup starts running immediately.
Continue with Checking the Completeness of the Oracle Database Backup to Disk.

42. Checking the Completeness of the Oracle Database Backup to Disk
This procedure describes how to verify that the DSU database was successfully saved to disk, which is the second step in Backing Up the DSU Manually.
What You Need
Successful completion of Backing Up the Oracle Database to Disk
How
Log in to the active Oracle node as user root.
Verify that the database backup procedure has finished by typing:
ps -ef | grep -i backup_db | grep -v grep
Navigate to the /data/backup/ODS/backup/logs/ RMAN_Backup_DB.log backup log file and verify that the date of the log is correct.
Continue with Setting Up the LTO2 Tape to Save the DSU Data.

43. Setting Up the LTO2 Tape to Save the DSU Data
This procedure describes how to set up the system to save the DSU data to tape, which is the third step in Backing Up the DSU Manually.
What You Need
Successful completion of Checking the Completeness of the Oracle Database Backup to Disk
How
Connect to the MAU and log in as user root.
The status of each system and service group in the cluster is shown.
Verify that the backup server virtual IP address on the HSBN is listed in the local MAU hosts list, for example, nsrhost_vip.
Select the Volumes tab, and then verify that there is enough space on the cartridge.
Continue with Backing Up the DSU to the LTO2 Tape.

44. Backing Up the DSU to the LTO2 Tape
This procedure describes how to back up the DSU, including the database and the file systems, to the LTO2 tape unit using the Network Administrator. This is the final step in Backing Up the DSU Manually.
What You Need
Successful completion of Setting Up the LTO2 Tape to Save the DSU Data
How
From the MAU main console, under the NetWorker Groups section, select Manage Groups.
Right-click the group to be backed up, and then select Start.
A confirmation message appears.
Click Yes.
The backup begins.
When the backup is completed, a message appears verifying the successful manual backup of the DSU.

45. Some Best Practices for Writing and Editing Modular Documentation
Topic types must not be mixed (Chunking)
Topics must be standalone (Chunking and Linking)
Titles must be unique and descriptive (Labeling)
Related topic links must be meaningful (Linking)
Topic collections must be meaningful and reader-focused (all three)

46. Takeaways
Readers want the documentation we send them to be accurate, clear, relevant, and accessible.
Our role as reader advocate is critical in modular documentation.
We must learn to become experts in and educators for modular documentation.
We must ensure that topics are chunked properly, labeled correctly, and linked appropriately.
Applying some best practices will make these tasks easier.

47. What questions do you have?

48. To Learn More:
Technical Communication Body of Knowledge (TCBOK): information/designing-and-developing- information/editing-modular- documentation/

49. #tcworldIndia2019 Thanks for listening! @reb_yoel @tcworldIndia
Yoel Strimling