Documenting Your Sisense System
How should you document your 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 may not be 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.
Introduction/Overview
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.
Standard Templates
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 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 for 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.
Documenting ElastiCubes
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 the 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 masse or present it on a Sisense dashboard like a conventional data dictionary. Cross your fingers for a future update! See our blog post Sisense Data Models Data Dictionary for info on our Data Dictionary Application for Sisense Data Models. Also, beginning with L2023.6 Sisense provides a list view for data models. This adds the capability to view a data model as a list with editing capability that among other things allows you to add and edit Tag and Description info for both tables and columns. Check it out after you update to L2023.6.
Miscellaneous Documentation
You should also document other areas such as plugins, custom palettes, etc. See the screenshot below for a typical documentation table of contents list.
Documentation Tools
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 a 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 online to ensure 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.