Documentation for Cognos Analytics is one of those things that doesn’t come with it. You have to create it yourself or look for a third-party product that might meet all or part of your needs for documentation. Creating it yourself can be difficult primarily because getting access to all of the Cognos metadata required to make it successful is not easy.
Let’s take a look at what these areas might look like starting with completeness.
In the figures shown below we see documentation for a report titled Order Summary. In actual practice this is a single, streaming web page that contains sections covering description, create date, active status and other key attributes such as package and model dependencies, data lineage, data sources, model usage, change history, etc.
For the sake of example these are being shown as single images to highlight key areas of the documentation.
The documentation examples you’re seeing in these graphics are created instantly at the same time that the actual object itself is created. This is done through a process in conjunction with the Cognos Content Store. Whenever an object is updated or changed that new version is automatically documented and the previous version’s documentation is archived as part of a version control process, but is also available as reference within the documentation for the current version of the object.
Getting to the documentation should be as easy as getting to the report itself. For this reason the best thing to do is to simply organize all of the documentation in a way that follows how Cognos Analytics itself has structured its content. In the graphic below you can see how the documentation structure mimics that of Cognos analytics making it instantly available. Each item shown is a hyperlink for the same CA folder which contains each object’s documentation.
Note in the images below that the folder structure of the documentation is exactly the same as that of Cognos Analytics.
The flow and structure of the documentation goes from general information to a more detailed level such as data lineage, main query data items, database items, etc. All of the documentation for every object is organized the same way so you always know where to look. Plus, hyperlinks make it easy to quickly go to exactly what you need.
When a new version of an object is created it automatically becomes the active version for that object while all previous versions are also retained and archived. This makes it possible to compare any two versions from the past or the current version with any previous version (version control). Plus, for control reasons should it be needed, it shows exactly what the report contained for data, calculations, filters, etc. during a given time period.
This capability also makes it possible to capture all changes made from version to version over time (change history). See image 10 below.
An important point here is that because all of this metadata is available for each object in the Content Store, it’s available for analyses. This makes it possible to do analyses across the entire Cognos environment. So if you needed to know which databases or data items are used, and where they are used, this is a simple analysis to perform.
Does everyone that uses Cognos Analytics need this level of documentation to successfully manage their Cognos operations? Maybe not, but when you do need it can often be of critical importance particularly for things like HIPPA or SOX compliance. And knowing exactly what data are being used and where, along with how security is being applied, are also critical requirements in virtually every reporting environment.
© 2020 Envisn, Inc. All rights reserved. Tools for Cognos