Designing%20Object-Oriented%20or%20Modular%20Documentation

1
Designing Object-Oriented or Modular Documentation

• Presented by
• Visnja Beg
• November 21, 2000

2
What is modular documentation?

• written in modules or chunks
• pieces of information that can be used in a
  variety of outputs
• ideal for reuse of information
• Write once. Use anywhere.

3
Advantages of modularizing documentation?

• easier to update since you only update
  information once and it is reflected in every
  instance of that module
• less risk of changes not being reflected in every
  place the information is found
• easier to produce solutions documents that pull
  in information from many sources

4
The 4 elements of designing modular documentation

• standard writing style
• procedural as opposed to conceptual components of
  information
• encapsulate the information
• use tools suitable to the modular approach

5
Standard writing style

• each component must be written in a uniform style
  
• need to use a style guide
• need to use a grammar reference
• all writers need to strictly adhere to the guides
  and common procedures for creating each component

6
Writing procedural components

• procedural components are easier to remove or
  include when needed
• still some need for conceptual components, but
  major portion of functionality should be
  documented procedurally
• closer to the Information Mapping model

7
Encapsulating components

• components that can stand on their own and do not
  depend on other parts of the documentation to
  render them useful
• task-based or procedural components are naturally
  encapsulated

8
The tools

• For writing
• tools should allow you to structure and tag your
  text according to the subject matter rather than
  typographical format
• tools that allow you to use meta-language for
  better search capabilities according to content

9
The tools

• For writing (cont.)
• FrameMaker SGML and XML are all conducive to
  modular documentation because you can create
  content-based DTDs
• XML and SGML enforce structure for information
  modules using the DTD and writers can concentrate
  on the content

10
The tools

• For writing (cont.)
• on a smaller scale, you can use FrameMakers
  conditional text feature to modularize and then
  reuse documentation modules
• HTML is also a tagging language but its tags
  reflect the presentation format, not content

11
The tools

• For storage
• store modules in a database-type information
  management system that enables searching and
  retrieving, while enabling document management or
  version control

12
The tools

• For storage (cont.)
• tools such as MKS Toolkit and Microsoft
  SourceSafe can be used even though they are
  geared to software development and storage of
  software components
• others are on the market, such as Chrystal
  Softwares Astoria, that address the content
  management needs of the tech pubs industry

13
Conclusion

• designing modular documentation requires careful
  planning and a few prerequisites
• once all the pieces are in place, the final
  product is easier to create

14
Discussion

• What experiences have you had in creating modular
  documentation?
• Did your approach use any of the elements in this
  presentation?
• What were your experiences in transitioning away
  from the traditional book and chapter approach to
  designing modular documentation?
• What are your recommendations?