Help Documents

One of the eternal struggles with any BI project is documentation.  We bring lots of data content in from all over the company, often from groups who previously had conflicting definitions or are now sharing data with groups who have never used it before.  There are lots of different ways to share documentation (my personal favorite is to add descriptions and formulas to the objects so they show up as tooltips on the report), but the most common approach is some external document that is sent off to SharePoint to die.

Today I’d like to share an approach we used on a project once that brought the documentation directly into MicroStrategy in the form of a Help Document.

I can’t take credit for this idea, it was in place long before I joined the project, but I haven’t seen it anywhere else I’ve been and thought it needed to be shared because I love the idea so much.  As previously outlined, the need to have documentation about data and reports readily available is key to whether or not the system is usable by a casual user.  Of course the subject matter expert or report requestor don’t need this documentation (though sometimes we all forget just what this report does after awhile) but someone exploring the system or pointed to a report they’ve never used will definitely need a heads up.

Help Document Idea
An elegant solution is to create a Document in MicroStrategy that doesn’t contain any data sets but instead is a simple tutorial and data dictionary for the content near it.  For example, say that you have a folder with Profit and Loss financial data.  Traditionally, there’s all kinds of complex metrics and data levels that usually don’t exist in other places.  Next to the report (or suite of reports) could be a document called “P&L Help” that simply loads up some documentation right there in the browser.  This could contain the data dictionary, tutorial screenshots, or anything else you want to convey to the user.  This puts it right at their fingertips and in a place that’s very easy to find, searchable and easy to maintain.

Creating the Help Document
To create the Help Document, I prefer to use a feature new in 9.0: HTML Containers.  In this way, we can create some nice looking HTML layouts complete with images and everything, store it on the Web Server in an easy to access and modify location, and then simply have our Help Document in MicroStrategy load that content.  This also allows you to outsource the creation of the Help Document to someone who’s not familiar with MicroStrategy.

Step 1
Write your Help Document out using Word (I find this is the easiest)

Step 2
Save As Web Page Filtered (htm).  This will remove as much of the “Office Crud” from the HTML, but also give you a near perfect HTML representation of your Document.  For simplicity, save it with a name with no spaces or special characters.  Also note that Word will create a folder with the same name that contains any images and stuff.

Step 3
Copy the HTML file and folder saved by Word into a folder path on the web server.  I like to keep this in the same location that MicroStrategy is installed.  Preferably, create a folder somewhere on that server called HelpDocuments and place them in their own subfolder.  For example, HelpDocumentsPL for our P&L Report.  Rename the HTML file to index.html for easy linking.

Step 4
Create a new Document in MicroStrategy using the 01 Blank Dashboard template.  Hit Cancel when it asks for the Report Data Set, since we aren’t using one.

Step 5
Click on the grey background container object and then choose the Insert menu and HTML Container.  Draw your HTML Container to fit nicely in the grey box.

Step 6
Right click the HTML Container and choose Properties.  Select IFrame and enter the relative path into the IFrame source field:  /microstrategy/HelpDocuments/PL/index.html or whatever your URL is.

Step 7
Right click on the Layout 1 tab at the top and rename it to something more appropriate, like “P&L Help”.

Step 8
Choose the Format menu and select Document Properties.  Uncheck Always open this document in full screen mode.  This is on by default since we chose the Blank Dashboard template, but it could be disorienting for a casual user, who is most likely the person reading this document.

Step 9
Save and Close

Step 10
View your masterpiece in Web.  If the contents are longer than the frame, a scroll bar will be created.  Switch to Editable Mode in web and expand the grey background and HTML Container to the proper height and width.

Congratulations!  You’ve now created a very simple, high value addition to your system that is easy to maintain and will win you brownie points with your end users.