writing and editing modular documentation some best practices n.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
Writing and Editing Modular Documentation: Some Best Practices PowerPoint Presentation
Download Presentation
Writing and Editing Modular Documentation: Some Best Practices

Loading in 2 Seconds...

play fullscreen
1 / 35

Writing and Editing Modular Documentation: Some Best Practices - PowerPoint PPT Presentation


  • 157 Views
  • Uploaded on

Writing and Editing Modular Documentation: Some Best Practices. Yoel Strimling (Comverse) Based on a joint presentation with Michelle Corbin (IBM) at the 55 th Annual STC Technical Communication Summit, Philadelphia (May 2008). The Mechanics of Modular Documentation

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

Writing and Editing Modular Documentation: Some Best Practices


An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
    Presentation Transcript
    1. Writing and Editing Modular Documentation: Some Best Practices Yoel Strimling (Comverse) Based on a joint presentation with Michelle Corbin (IBM) at the 55thAnnual STC Technical Communication Summit, Philadelphia (May 2008)

    2. The Mechanics of Modular Documentation Some Best Practices for Writing and Editing Modular Documentation The Editor’s Role in Creating Modular Documentation

    3. The Mechanics of Modular Documentation

    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

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

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

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

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

    9. 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. Some Best Practices for Writing and Editing Modular Documentation

    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 (Linking) • Topic collections must be meaningful and user-focused (all three)

    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.

    13. Before…

    14. … and After (Concept Topic)

    15. … and After (Task Topic)

    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.

    17. Example

    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.

    19. Before…

    20. … and After (Concept Topic)

    21. … and After (Task Topic)

    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.

    23. Example (Concept Topic)

    24. Example (Task Topic)

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

    26. Example

    27. The Editor’s Role in Creating Modular Documentation

    28. The Editor’s Role in Creating Modular Documentation • Expert • Educator • User Advocate (“First Reader”)

    29. Editor As Expert • Information models • Usability research • Templates and style guides

    30. Editor As Educator • Continuous education • Implementation-level education • Frequent consultations with writers

    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

    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.

    33. Any Questions?

    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.

    35. Yoel Strimling, YoelAaron.Strimling@comverse.com