Create Social Documentation

Documentation is sometimes viewed as a necessary evil. But it doesn't have to be. Here's how to produce documentation that will be used.

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:

1. Prior to development: Identify and validate requirements and designs
2. During development: Specify what to build
3. 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.

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)

For more details on what to document, check out my book Star Schema: The Complete Reference. Detailed descriptions and examples can be found in Chapter 18, "How To Design And Document A Dimensional Model.”

I also discuss documentation of information requirements and business metrics in the course “Business Information and Modern BI.”  Check the sidebar for current offerings.

Document Information Requirements Graphically With BDM Diagrams

BI teams often struggle to keep the business engaged, especially during requirements analysis. This post looks at a graphical technique for documenting information requirements -- one that business people will read and respond to.

Keeping the business engaged is one of the keys to a successful BI program. One technique I have found to be very helpful on this front is Laura Reeves's Business Dimensional Model (BDM).

The BDM is a technique for documenting information requirements. Before I explain the BDM, a few words on the requirements themselves.

Information Requirements

Before you can design a dimensional model, you need to capture the business requirements that it will support. The most successful projects capture business requirements by working directly with people in the business, often through interviews or requirements sessions.

In my book, I suggest that as you organize your information requirements by business function.  You then state them in simple form: as a group of metrics and their associated dimensionality.

For example, a set of interviews about the taking orders might boil down to a requirements statement such as:

• Order Information by order date, order line, salesperson, customer and product.

The metrics that comprise the group are then fully documented.  For example, "Order Information" is further supported with documentation of:

• Order dollars
• Order quantity
• Cost dollars
• Gross margin dollars
• Gross margin rate

Relevant hierarchies in the dimensions should also be specified. For example, "Product" might be described as:

• All Products à Category à Brand à Product 

Finally, the major dimensions are cross-referenced to the metric groups in a conformance matrix.

These information requirements then drive solution modeling. The next step is to develop a top level dimensional model, and then a detailed database design.

(For more on developing and documenting requirements, including a fully fleshed out example, see my book -- it's listed at the end of this post.)

Getting People to Read It

When it comes to information requirements, you must ensure that the business stakeholders review and respond. (Better still is to involve the business in the identification and documentation process.)

In the book A Manager's Guide to Data Warehousing, Laura Reeves provides a graphical technique that helps keep the business's attention. She calls it the "Business Dimensional Model (BDM)."

This technique integrates nicely with the approach I've outlined above.

Each group of metrics is depicted in a simple diagram, with the metric group in the center and the major dimensions arrayed around it in circles.

For example, the Order Information metric group above might be documented thusly:

Within each circle, the underlined text identifies a dimension. Beneath the dimension, the level of detail applicable in the metric group is listed.

Additional illustrations document the dimension hierarchies. For example, the product dimension from the picture above might be documented like this:

The most detailed level of the dimension is shaded darkly. The arrows indicate hierarchies, going from summarized to detailed. Elements that will drive Type 2 slow changes have a shadow. Separate symbols (not shown) are used for junk dimensions, other derived elements, and future attributes.

People Like Pictures

I've found that using BDM diagrams dramatically increases the participation of business stakeholders. People look at BDM diagrams, understand them, and react to them -- often with great enthusiasm. That's a powerful aid in refining and validating your requirements.

These diagrams are also easy to produce using the built in drawing tools that come with basic productivity software.  This means you can often get business stakeholders to participate in their creation. For example, the pictures above were created in Microsoft PowerPoint using basic shapes and Smart Shapes.

Lastly, the ability to produce these diagrams using basic productivity software means they are easy to incorporate in the best format for this kind of documentation: the presentation.  I find the presentation format is far more likely to be reviewed than a word processing document. (More on this topic in a future post.)

Further Reading

As I said back in 2009, I am a big fan of Laura Reeves's approach to requirements and design. As you can see, there is a natural affinity between the BDM and the techniques I've talked about in the past.  I encourage readers to check out her book (see below).

More info about requirements and documentation can be found on this blog. Have a look at these posts:

• I first mentioned Laura's book in this blog back this post from 2009:  Recommended Books on the Data Warehouse Lifecycle (July 27, 2009)
• For an explanation of the three levels of a dimensional model (Requirements, Top Level Design and Detailed Design) see Dimensional Modelers Do Not Focus on Logical vs. Physical (July 5, 2011)
• For an example of a conformance matrix, see The Conformance Matrix (June 5, 2012)
• For an explanation of the type 2 slow change, see For Slowly Changing Dimensions, Change is Relative (October 9, 2007)

You can read more about the process of identifying information requirements in these books:

• For a full explanation of the BDM, see  Laura Reeves's A Manager's Guide to Data Warehousing (Wiley, 2009).  The BDM is covered in Chapter 7, "Modeling The Data For Your Business"

• The examples in this post are drawn from my book, Star Schema: The Complete Reference (McGraw-Hill, 2010)  A more fleshed out explanation of tasks and deliverables, with examples, cab be found in  Chapter 18, "How To Design and Document a Dimensional Model."  The examples from this post come from Figure 18-4 (which in turn builds on the star in Figures 3-3, and the hierarchies in Figure 7-3).

You can help support this blog by using the links above to purchase these books from Amazon.com.

[Edited 2/13/14 - Corrected the links, thank you for the emails.]