“It might be a little disorganized.”

One of my pet peeves with most in house documentation is its organization: There is isn’t any. And organization is vital for documentation to be effective. Without it the reader is left randomly bopping around the content trying to find their needle in the haystack. So, what does it mean to be organized?

  1. or·gan·ized/ˈôrgəˌnīzd/Adjective

    1. Arranged in a systematic way, esp. on a large scale.

    2. Having one’s affairs in order so as to deal with them efficiently.

Although this definition may be accurate, it is not specific enough in dealing with the issue at hand; effective documentation. I associate organized documentation with the following criteria:

  • It has a table of contents and/or index — You can find what you are looking for.
  • It answers the what, why, when, who, and how of system construction and operation — It answers specific questions.
  • It provides background business information — It describes within a business context.
    • Explanation of acronyms,
    • Summary of system interactions,
    • Contact information for major players,
    • History (if any).
  • It provides background technical information: — It describes the technical boundaries.
    • Overview of technical architecture;
    • Details of operating systems, server connections, and file locations.
  • It separates the business aspects from the technical details. – It removes convolution between business processes and their automation.
  • It can be used by all parties involved with the system, regardless of responsibility or background. – It establishes common ground from which to solve problems.

Now these are not absolutes but my own bias. However, I think any document organized in this fashion would be the start of a good effort and provided dividends later. I personally like the following general outline for my documents:

  1. Cover Page
  2. Revision History Page
  3. Table of Contents
  4. Summary Area
  5. Background Information
  6. Business Area
  7. Technical Architecture
  8. Standard Operating Procedures
  9. General Notes
  10. Idiosyncrasies*
  11. Index

* – If you don’t think your system has idiosyncrasies you haven’t delved into it deep enough.

It covers the items from the previous list and it starts with very large concepts and digs in deeper as you get further in. I can scan the table of contents to find the general area I find important or I can search the index for the specific item I want to know about. If I read the whole thing, I should have a pretty general understanding of the business process involved and how it was automated.

Keep in mind that organization is always an on-going event. As the system changes, so does the documentations structure and content. As the system lives, so does its documentation.

Once a document is organized, it may still not be readable….Which is what we’ll cover next.

Leave a Reply