Documenting a TM1 solution

[Bakkone]

Hi everyone!

I'm looking to make some proper documentation in regards to our TM1 solution. I find that during the years I never really found a good template for doing so. Most of the templates and documents I've been asked to fill out seem to be made with "normal" software development in mind. There is way too much focus on technical things. I keep starting to just write down every subset, view etc... but I dont really see the point of it. I know there is software out there that can help me with listing all of this. But I'm not really interested in buying anything.

Does anyone have any good advice on what to put in such documentation? What is the table of contents of your TM1 documentation? Are there several documents? Whats the structure of your documentation?

Any advice would be much appreciated.

Thanks
David

[paulsimon]

Hi

End User documentation will depend very much on the particular application, so I can only really comment on Technical documentation. I work as a contractor so I frequently go in to maintain, enhance or replace existing systems, and more often than not the original developers have left.

What I would like to see as a bare minimum is :

a) Entry Points to the application. By an Entry Point I mean the external interface of the system to the outside world. Typically in any application there are processes that call other processes, however, there should be relatively few top level processes. If the process is only intended to be run from an Action Button on an Excel sheet, then the sheet rather than the process is the Entry point. Other possible Entry points might be an Excel Sheet with a Print Report Job or VBA Macro used to generate a series of reports or data collection templates.The entry points should be documented in terms of triggering events. These will either be on a timed basis - typically chores, but possibly Scheduled Tasks, or they will triggered by some event such as Server Startup, or a user request such as Close the month. Any other automated entry points should also be documented, eg a Data Warehouse application using TM1RunTI to trigger a process when it has completed its ETL. Ideally the non-chore entry points should be structured in the order in which they are typically run using the application folders, eg folders 110 Load Actuals, ... 0220 Enter Forecast ... 390 Month End Close.... 630 Year End Close.

b) A list of cubes, dimensions, processes, and chores that are still in use in the application. You can often spend a lot of time investigating processes, etc, only to find that they are no longer used. Even if this is not present, if you at least have (a) then you can derive this by tracing through from the Entry Points. I have a utility that produces a what calls what list of processes.

c) Processes and Rules should be commented. Each process should at least have a description on the Prolog saying what it does. I tend to find that where technical documentation is held separately to the system objects, that it quickly gets out of date and out of date documentation can be worse than no documentation. Comments in the code itself are more likely to be updated as the code is updated. However, it does require a certain amount of discipline and a certain amount of empathy with the developer who might come after you to try to think about whether the bit of clever coding you are writing is something that is self-evident, or does need a comment to explain what, why, and how it is doing what it is doing.

d) Exceptions. I think you have to assume that anyone who comes after you will have a certain amount of business and technical knowledge. No level of documentation is going to allow a complete novice to do anything more than run the system. However, if you know that something is being done in an unusual way then you should highlight that. Eg most Actuals are loaded directly from the general ledger, but this particular cost centre enters them manually, or most dimensions are maintained by processes that use this set of csv files, but this dimension hierarchy is maintained manually. You should also include reasons for the exceptions. For example, there might be a good reason why the dimension is maintained manually, or it might be that no one ever got round to writing a process. There is nothing worse than taking over a system that is working in an unusual way and not knowing whether there is a reason for that, or whether it was just that the previous developer didn't have the time or the knowledge to do it differently, which means that you can change it.

e) The technical basics - how many environments there are, whether the environments have separate web servers, application servers, sql servers, TM1 servers, etc. For example the production environment might have two or more web servers to spread the load, while development might only have one. Licensing details on users. Where to get the passwords for TM1 Admin, passwords to RDP on to the servers, or contact people in IT.

Regards

Paul Simon

[Bakkone]

Thank you so much for your input.

Do you have any opinions in regards to documenting business logic? My current situation is that there aren't really any requirements to refer to.

[tomok]

When it comes to documentation you should always follow the golden rule, document for others what you would want documented for yourself. In other words, if the system was suddenly dropped in your lap to support, what would you want to know about it from the guy who built it. Simple as that.