Best practice how to document a Planning model

[craig_karr]

We have around 30 different applications at our Planning website and we are five guys who have built them and administer them. We have been thinking of documenting these models so that any of us could update any model. We don't want to spend to much time creating and maintaining the documentation itself, but we think it would be handy so that you can easily get a picture of how each of the models work and what steps you need to perform when updating a model (i,e adding d-list items etc). Is there anyone here who knows best practice for documenting Cognos Planning models? Does anyone have a template we could use?

We think that the Cognos Planning Manager tool is a good start, but we think that we also need a little more information about each model in order to be able to back up each other. Perhaps some descriptive text that explains the model, but it can't be too extensive because then no one will read it and it must have a very good disposition so that you can easily find the information you are looking for. Any advice is very welcome because we really don't know where to start when trying to document these models.

[ykud]

Hello, Craig.
Finding out a format for documenting EP models is a very interesting task (especially, because that's what I've got to do in nearest month).
Manager's Flowcharts are very useful, especially if making them a bit IDEF-stylish (a bigger scale blocks with ability to drill-down into concrete apps). So we usually use Flowcharts extensively.
But it's often hard to explain some technical solutions or greater scale business problems in a flowchart. There's usually  about 5-10 imprecise technical decisions in a model + a 1-5 A4 schemes for explaining business tasks.
That's what I plan to get in a month:
- A lot of Flowcharts, detailing the realization
- Some text on the "thin" moments and technical tips (ex. Rolling budget is constructed via 3 alloc cubes). That's what we got wiki for.
- Schemes for business meaning. Visio ;)

[andrewbho]

There really is no best practice, but there are a few guidelines.

I would recommend staying away from Manager Flow Charts where possible, but I would build out a Manager Maintainence Menu to Update, Dlists, or to run macros, etc.  Everytime you create a report, you create another object that is tied to the underlying list, cube, link.

We usually flow chart out the entire process in Visio and supplement all descriptions in Word.  The most important thing to document is your d-links, specifically the order the dlinks need to run.  Also, it is important to document access tables and saved selections and which ones are tied to frequent changes.  We also details all dlists and their calcs in our system documentation to make sure that if anyone changes any calcs. we have the original.

We try to document everything and pretend to go through a rollover cycle.  This helps us catch any gotchas and makes sure that the client knows how to maintain the system once our consultants leave.

No matter which way you go, documenting a model or any application is challenging.  What I would recommend is setting the appropriate expectation with the client and negotiate the level of detail.  It's a lot different documenting an application for someone who doesn't even understand the product.

[ykud]

And how do you document system changes? Via Change Requests? Do you actualize overall system documentation after implementing changes?

I regard Manager Flowcharts as an invaluable tool, allowing fast and simple model studying. And refresh options highlight all the changes.
We build assumptions(main dlists (GL, clients etc), allocations (Cahflow to P&L) and even access tables (as cubes whether possible) section as a part of model, and this part ensures propagation of changes on all system. This part is allways realized in Manager.

[andrewbho]

Any system changes, should be handled through documentation of the change as well as any changes to the documentation.  If you build a complex model with 100's of links, you are going to have a nasty manager report, espeically if it is an Analyst only model.  If you have several manager menus and if you ever want to delete a cube or link or change them, it may be difficult.

Any way, it's not a big deal.  If this was an IT owned system, the any benefit would be eliminated because there would be a ton of paperwork like other systems.

[marcdubois]

Hi, first time on board  !!   

for this we use a nice tool EA from sparks, lot of thing too type but very handy for the futur !!

regards   

[marcdubois]

oooops i mean sparx systems,  entreprise architect  v 7.01

regards

[Edatum]

For those who want  to create a detailed document of Analyst objects, here is a trick:

1. In Analyst, go to File>Library>Objects.
2. Highlight and drop all the objects you want to document into the lower pane.
3. Click the print icon on the middle toolbar.
4. In the Print Options, select the information you want to include.
5. Then select Export to filetype. Change the file type to HTML.
6. Click the browse button and save the file as HTML. Make sure to use the *htm extension.
7. Click Print. The process will take a few minutes depending of the number of objects.
8. Open the html file and copy the text into a Word document. Format as necessary.
9. Now tell your boss/client you spent days doing this and ask for a day-off. :)

[JaromirSeps]

Hi,
we also have very large models, and we are using mostly manager, mainly because of updates, as Ykud was saying. Initially, when you start the project, it's good to document important things and decisions elsewhere - in a document describing, why and how is done some special thing.
Manager is not an ideal environment, but it is enought to put there flowchart + update screens with macros + access tables maintenance all with reference to other documents like excels, txt files, etc. if those are used.

[jan.herout]

Manager flowcharts are indeed invaluable.

On top of that, I believe it is a good idea to document the most important dimensions that form the macroskeleton of the application, along with description of what you can and can't do on them. For example:

- is it allowed to create dlist item into 5 Scenario, or will it break allocation rules?
- if allowed, what other dimensions should be updated (ideally this administration would be automated)?

Along with that, description of actions that needs to be done on the model when month / quarter / year is closed should be prepared.

If this type of documentation is missing, generally you will have problems when person of system administrator changes.

[dermeister]

Edatum-
I haven't tried your Analyst trick, but I'm really excited about the prospects! It may help my golf game.  ;D

[abernabr]

This actually works pretty well!

However, I had to force the system to save the file as a .htm (just choosing the option didn't change the file from a .csv to a .htm).

[sascha]

I usually use exactly this file to process it by a small programm call 'analyst documenter' which we offer to our clients. The documentation tool reads the (sometimes very big, e.g. 20 megs) html file and converts it to a browsable 'book' with an index that can be integrated into Connection. The documentation itself will take place directly within the analyst objects.

Screenshot of tool:


Screenshot of Connection:

[ykud]

We've got python scripts to generate .doc files from  Anyalyts csv generated objects descriptions )

[ashishberry]

Sascha and ykud,

I noticed that two have programs and macros designed to pull relevant information from the analyst generated document and put it into an easily read format. Are there any freeware tools that you are aware off that I could download that do the same thing? I've googled around a bit but was unable to find one...If you guys have any ideas or suggestions it would be greatly appreciated.

[sascha]

No freeware tools that I am aware of, sorry.