The Importance of Being Documented
Wednesday, December 12, 2012 at 9:44PM 
Documentation of implementations of Business Intelligence platforms, or GIS systems varies greatly from organization to organization. As a new architect or platform administrator you may find yourself scrounging for every little scrap, every tiny morsel of documentation you may be lucky to find. It is often a true hodgepodge, what we find that passes for documentation. Here are some broad categorizations:
1) The IKEA instructions
Those wordless pages with pictures familiar to anyone who has ever shopped at an IKEA can either provide easy guidance or a rather sleepless night. Putting together something called a Hakan (Swedish for either a former NHL’er or meaning “There goes your evening”) can range between easy or rather difficult depending on the visualization interpretation of the person in front of them.
IKEA instructions can be a gem or a bane to a new architect making sense of a production
environment. Certainly you can put the screenshots together and learn the steps taken to build the environment. But often, the rationale and the why get lost in the visual interpretation.
Questions like:
- Why did that install step fail and why was it allowed to go to production?
- I see a script was run to get past a validation step, why?
- One server didn’t use an installer account, let me guess why?
For a SAS BI environment, you typically want to extract information like:
- Which software depot was used where?
- Is there a plan.xml file and is it used in all cases?
- Locate the deployment registry and instructions.html file to get more information on the web application server configuration and what was installed.
- Use the Web Administration console to look at the configurations of all of the web applications on the midtier.
And this is only the start of piecing together our “Hakan” or BI environment.
Enhancing the documentation involves putting the why and how into it. Use images liberally, but explain any deviations from the norm (i.e. use of non-standard ports, or changes to the normal configuration and why they were made). This will go a long way to make sure documentation leads to repeatable implementations of the platform. You also need to carefully inventory what has been installed, perhaps in a matrix and attribute these applications to an order and license. If there are ever any discrepancies with the vendor, you now have an easy way to track what may or may not be included in a proper software order.
The IKEA instructions give us at a minimum the bread crumbs to find our way out of the forest.
2) Where or where has our little documentation gone?
The architects and administrators that fit into this category can only wish they had the handy
“IKEAesque” screen captures of installations and configurations. Often a good admin can piece together much of it through looking at the relics of the installation such as deployment registries and if it still exists on the servers, the Software depot or package used. When the deployment deviates from the norm or best practices, we are often in a pinch of trouble from the outset. In a customized environment, perhaps one that utilizes multiple tiers or clusters of servers, it is indeed a challenge if you need to recreate such a thing for a new platform release.
So where do we start?
The SESUG paper from Brian Varney on Documenting an Undocumented Environment gives some great ideas to proceed ahead including examining existing logs to determine who is using what applications. The logs for Web Report Studio and other web applications for example provide some excellent information that can be pulled about their usage. For Linux or UNIX environments, you may find using TOP or TOPAS (depending on availability on the server) to be useful to see what people are commonly running in the environment. Sometimes a quick e-mail or call to some of the “power users” can help fill in the gaps on why an environment was customized or didn’t follow the normal vendor best practices.
There are a few good practices to adhere to in getting documentation going and in good shape:
1) Application matrix – tying installed applications to servers. List the Ports these applications use and include information on dependent programs and locations of files that use these applications.
2) Install directory – subdivide this for all software clearly labeled for order and version.
3) Interaction with vendor – document any hotfixes or internal documentation the vendor may have to fix an application issue.
4) Architectural diagrams tied to applications. In multi-tier or distributed environments, it is good to know both the number of cores on a server as well as what is installed on them.
And for those lucky enough to walk into an organization with stellar documentation, we would suggest a laudatory e-mail, or better yet, offering to buy a beer for your diligent and thoughtful predecessor. That is indeed something worth celebrating.


























