Useful documentation gets used -- during all development phases, and by all interested parties.Burdensome methodologies often expend precious hours producing documentation that is hard to use. Many projects leave behind fat binders of text that hardly anyone will ever open. These examples have given documentation a bad name.
The good news is that documentation can be done right. It does not have to be a drag on project time, it does not have to be a chore to read and review, and it does not have to be something we interact with alone.
Why we need documentation
Documentation is not an after-the-fact explanation of what has been built. Used properly, it is a central component of the entire lifecycle of a BI solution.
Important uses include:
- Prior to development: Identify and validate requirements and designs
- During development: Specify what to build
- After development: Educate business people and support personnel
Of course, there are many other areas in which documentation has value (program planning, governance, change management, etc.). These three above are sufficient to illustrate the value of social documentation.
Useful documentation should be easy to read and discuss. It should also not be burdensome to produce. Three principles shape social documentation.
Social documentation is the focus of collaboration.
Whenever possible, I recommend to my clients that we use PowerPoint for documentation. Why? Word processors are tailor made for reading, which is a solitary activity. Presentation software is tailor made for collaboration.
Social documentation is easy to navigate.
Support "random access" rather than "sequential access." Presentation software is great for this; we can easily sort and navigate slides by their titles. This can also be achieved using document maps or outlines.
Social documentation is not prose.
Each slide in a presentation, or section in a document, should be set up to capture essential information in a consistent format. This format may be tabular, diagramatic, or both. Your subject matter will dictate the appropriate format.
But here is the important part:
- No paragraphs
- No prose
- If using PowerPoint: No bullet lists. (They're just a back door to writing paragraphs.)
Uses for social documentation
I find the presentation format excellent for defining program priorities, defining project scope, capturing business requirements, developing top level information architectures, and a variety of other tasks. For specifications, a word processed document with multi-level headers and a document map typically fits the bill.
When documenting business metrics for a dashboard or scorecard, for example, set up a PowerPoint presentation with one slide per metric. Use a standard tabular format to document each metric. This documentation is easy to produce, review and revise, as I will discuss in a moment.
Where presentation software is not practical, word processors can be used in the same way. Divide the document into sections, activate the contents sidebar, and use a consistent tabular format.
Of course, not all documentation is captured in this manner. For example, we might use social documentation to capture a top level star schema design, then use a modeling tool to produce a detailed design.
Advantages of Social Documentation
This simple approach has numerous advantages.
Frictionless and Comprehensive
During requirements specification, social documentation allows you to capture the necessary information in frictionless and comprehensive manner. A standard tabular format, for example, ensures the same items are filled in. The presentation itself is easy to navigate via sections and slide titles.
Engages with the business
Social documentation invites collaboration. Give people a big fat binder and their eyes will cross. Show them 5 or 6 slides that capture the business metrics they care about, and they will give you feedback.
I always have my laptop with me, so if I happen to be in a room with a SME, I can pull it out, flip to the correct slide, and ask a question.
Incidentally, collaboration with the business is one of the cornerstones of the agile manifesto.
Reviewed together, rather than in isolation
Ever sent out a fat document for review? If you have, you know the results are not good. Most people will not review it by the deadline. When reminded, they will say, "it looks good." A precious few will provide detailed feedback.
Social documentation transforms this process. A review is conducted by bringing people into a room and reviewing the deck. Any agreed upon changes are made directly to the presentation slides.
The documentation is now ready for the next tasks: guiding development and then serving as the basis for education.
Learn More
Read more about documenting BI program activities in these posts:
- A great diagramming technique for information requirements: Document Information Requirements Graphically with BDM Diagrams (February 10, 2014.)
- Recommended approach to documenting dimensional designs: Dimensional Modelers Do Not Focus on Logical vs. Physical (July 5, 2011)
I also discuss documentation of information requirements and business metrics in the course “Business Information and Modern BI.” Check the sidebar for current offerings.
