- Jim Thomas
Good Governance: Documenting your Sisense system
Updated: Dec 8, 2022
How should you document you Sisense system to support maintenance, enhancements, future growth and failure recovery? Some of the topics that should be documented are obvious: Dashboards and ElastiCubes. Others maybe not as obvious: scripts, custom palettes, etc. When considering how to document, it is desirable to adopt a standardized, templated approach to help assure each topic is consistently and efficiently documented.
An approach that has worked very well for me across multiple Sisense installations is to define a documentation map (outline) and then insert the documentation details into your documentation in standard table structures that occupy the appropriate positions in the map. See the example below for a sample Sisense documentation map.
It goes without saying that your documentation should include an Introduction/Overview that describes the Business Case and how it is addressed by your Dashboards. You should also include a section that describes how your documentation is organized. If your system is large, you may do well to segment your documentation for each major Business Case area. Examples might be Sales, Finance and Operations.
Once your documentation map is established, you can create your standard templates. I will provide examples for Dashboards and Widgets in this post. As I mentioned above, table based templates have been well received and are easy to reuse. For Dashboards, these involve a defining a Dashboard template and a Widget template. The Dashboard template is reused for each dashboard and the widget template is reused for each widget. Screen shots are made each Dashboard and Widget to complement the tabular information. The items that should be documented for each include:
Dashboards: Description, Type, Category, Dependent Filter(s), Independent Filter(s) and ElastiCube name. Type and Category are arbitrary descriptions that you may define and use as appropriate.
Widgets: Description, Type, Drill Down(s), Info Text, Widget Script(s), Widget Filters, X-Axis, Values and Break By. X-Axis, Values and Break By entries listed are based on a line chart and will change or not be applicable for other widget types. Adjust as necessary. You may wish to document additional items in widget configuration, but I have found this list to be satisfactory.
See the screen shots below for examples based on the Sisense demo dashboards.
ElastiCube documentation templates are essentially Data Dictionaries for the ElastiCube tables and columns with references to the data sources. Be sure to include connectivity information. I like to create a page for the overall ElastiCube and a separate page for each table. Custom column scripts should be documented as part of the corresponding EC table data dictionary. SQL Function tables should document the columns and provide the commented SQL code used to build the table.
Starting with v7.2 you have data dictionary capability in the ElastiCube Manager. This allows you to define descriptive information for tables and columns. Tables also allow you to define tags to make it easy to designate types of data or related data. See an example in screen shot below from the Sample Healthcare EC. This is a very nice feature and really the only thing missing is the ability to export this information en mass or present it on a Sisense dashboard like a conventional data dictionary. Cross your fingers for a future update!
You should also document other areas such as plugins, custom palettes, etc. See the screenshot below for a typical documentation table of contents list.
A note about tools for documentation. I'm sure we have all used word processing tools such as Microsoft Word or Google Docs for documentation. There are also a number of online tools that support documentation. I have grown fond of using Microsoft OneNote to support documentation. OneNote's notebook, section and pages structure does a very nice job making documentation organization easy. I like to put each topic on page and use sub-pages for individual items. Example: Using a page for a Dashboard and sub-page of that page for each widget (see the first screenshot above). I also find working with screen shots to be easier with OneNote than word processors. OneNote also has the advantage of being free. Notebooks are readily shareable on-line to insure that all members of your team have browser or client access to view and update (if appropriate) your documentation.
I hope this post is helpful for those thinking about how to document their Sisense system. If you have comments or questions, please comment on this post or contact me directly using the contact info for my main site.