1. Designing Object-Oriented or Modular Documentation Presented by Visnja Beg November 21, 2000

2. Visnja Beg2 What is modular documentation? n written in modules or “chunks” n “pieces” of information that can be used in a variety of outputs n ideal for reuse of information n “Write once. Use anywhere.”

3. November 21, 2000Visnja Beg3 Advantages of modularizing documentation? n easier to update since you only update information once and it is reflected in every instance of that module n less risk of changes not being reflected in every place the information is found n easier to produce “solutions” documents that pull in information from many sources

4. November 21, 2000Visnja Beg4 The 4 elements of designing modular documentation n standard writing style n procedural as opposed to conceptual components of information n encapsulate the information n use tools suitable to the modular approach

5. November 21, 2000Visnja Beg5 Standard writing style n each component must be written in a uniform style n need to use a style guide n need to use a grammar reference n all writers need to strictly adhere to the guides and common procedures for creating each component

6. November 21, 2000Visnja Beg6 Writing procedural components n procedural components are easier to remove or include when needed n still some need for conceptual components, but major portion of functionality should be documented procedurally n closer to the Information Mapping model

7. November 21, 2000Visnja Beg7 Encapsulating components n components that can stand on their own and do not depend on other parts of the documentation to render them useful n task-based or procedural components are naturally encapsulated

8. November 21, 2000Visnja Beg8 The tools For writing n tools should allow you to structure and tag your text according to the subject matter rather than typographical format n tools that allow you to use meta- language for better search capabilities according to content

9. November 21, 2000Visnja Beg9 The tools For writing (cont.) n FrameMaker + SGML and XML are all conducive to modular documentation because you can create content-based DTDs n XML and SGML enforce structure for information modules using the DTD and writers can concentrate on the content

10. November 21, 2000Visnja Beg10 The tools For writing (cont.) n on a smaller scale, you can use FrameMaker’s conditional text feature to modularize and then reuse documentation modules n HTML is also a tagging language but its tags reflect the presentation format, not content

11. November 21, 2000Visnja Beg11 The tools For storage n store modules in a database-type information management system that enables searching and retrieving, while enabling document management or version control

12. November 21, 2000Visnja Beg12 The tools For storage (cont.) n tools such as MKS Toolkit and Microsoft SourceSafe can be used even though they are geared to software development and storage of software components n others are on the market, such as Chrystal Software’s Astoria, that address the content management needs of the tech pubs industry

13. November 21, 2000Visnja Beg13 Conclusion n designing modular documentation requires careful planning and a few prerequisites n once all the pieces are in place, the final product is easier to create

14. November 21, 2000Visnja Beg14 Discussion n What experiences have you had in creating modular documentation? n Did your approach use any of the elements in this presentation? n What were your experiences in transitioning away from the traditional book and chapter approach to designing modular documentation? n What are your recommendations?