Documenting FM process

[k2]

Hi there,

Could any one please share the document for documenting the Framework Manager which contains the information about each query subject,relationships,securities,filters,namespaces etc...

This document will be helping out to give a fair idea about the particular model/package for new developer. Please let me know if any further information required. Cheers

[MFGF]

Hi,

Take a look here:

http://publib.boulder.ibm.com/infocenter/rentrpt/v1r0m1/index.jsp?topic=/com.ibm.swg.im.cognos.ug_fm.8.4.1.doc/ug_fm_i_FrameworkManager.html

Regards,

MF.

[Lynn]

My general advice is to keep it short and simple (though I, myself, have never been accused of being concise :)). Focus on big picture concepts, not minutia. There isn't much point in writing about what can be easily seen from looking at the model. Answer the question "why" more than "what." Think of what you would point out to a developer if you were sitting together going over it.

Details worth stating can often be done right within the model itself. If, there is an expression for a query item that warrants explanation then include the comment in the expression directly. Keeping this type of comment directly with the code will give it greater hope of remaining current should the expression change. (You can do this in RS reports also). For example:

Code Select Expand

( ( [Database Layer].[FactTable].[EMBOOK] * .10 ) / 12 )

#/* Monthly interest is computed as 10% of book value spread evenly over 12 months */#

The model should contain screen tips for presentation query subjects and items. These are most often business definitions and can be exported out of the model for use in a quick reference document for users/authors.

I don't have a document I can give you, but below is an outline of what I typically cover. Of course you've already identified some of the broad categories in your question so here are a few thoughts on the kinds of things to cover - BRIEFLY). The longer you make it and the more detailed you get for no good reason ... the sooner it will become out of date and irrelevant.

Outline: In each category, explain any deviations from typical best practices.

• Overview (a paragraph or two about the high level purpose of the model, subject areas supported, etc.)
• Standards/Conventions (any naming standards, general rules or practices)
• Data Sources (what are they; database/schema information; Cognos data source information; batch window considerations (if any); refer to related documents such as ER diagrams or environment diagrams)
• Model Layers/Namespaces (description of the approach taken; anything not easily understood just by looking at the model)
• Diagram Notes (any oddities that might be present in defining relationships, aliasing needed and why)
• Parameter Maps (what they do and why)
• Security (approach taken and rules enforced, authentication source, groups/roles, etc.)
• Multi-Lingual (if any, what languages are supported, modeled for query subject/item names and/or database content?)
• Query Subjects/Stand Alone Filters (if there is nothing to say about these other than just listing them, then DON'T! Anyone can see what they are by looking at the model. Often I find that anything interesting worth saying on these is covered in other sections or in screen tips and model comments in the FM itself.)
• Packages (what each is intended for, any security there)
• Usage Notes (anything special report authors might need to know in using the published packages)
• Performance considerations (relevant benchmarks that may assist later performance testing when changes are made to the model)
• Future plans (anything in progress but not yet complete? anything planned but not yet started with thoughts on how those new things will be integrated)

Of course every model has it's own unique personality and there may be other categories to include, but hopefully this offers a starting point.

[prikala]

Details worth stating can often be done right within the model itself. If, there is an expression for a query item that warrants explanation then include the comment in the expression directly. Keeping this type of comment directly with the code will give it greater hope of remaining current should the expression change. (You can do this in RS reports also). For example:

Code Select Expand

( ( [Database Layer].[FactTable].[EMBOOK] * .10 ) / 12 )

#/* Monthly interest is computed as 10% of book value spread evenly over 12 months */#

Nice trick, comments in RS expressions, excellent!
Is the use of expression comments in macros documented somewhere? I tried to search for something like this some time ago but found nothing (in 8.4.1 documentation for RS).

[Lynn]

I think it is one of those things that Cognos only tells the cool people :)

Actually I don't remember how I stumbled across it but have used it for a number of years now. Vey handy indeed!

[blom0344]

To dwell a bit further on the topic of model documentation. I need to come up with some sort of user documentation for DMR models (which will be solely used in AS / QS) So ,any "Cool" examples or ideas on how to structure this?

[Lynn]

User's don't read user guides which makes the task considerably easier.  :D You can even weave in the occasional insult which will, of course, go unnoticed.
</silliness>

Actually I've not done one for a DMR model, but I guess I'd go about it in a similar fashion to ones I've done for cubes and relational models.

I think a data reference section is important. This shows the expanded hierarchy along with the business definitions for each element. Usually I export this from screen tips in the model (using language translation export) and pretty it up in a Word table. This helps them understand what is available and how it is structured so they can navigate well.

My guides also include a functionality reference section. Here I cherry pick the features of the tool that are most commonly used and most relevant to their requirements. These are somewhat isolated bits of functionality (organized around the various toolbar and menu options). Each is described briefly and, in some cases, including an example that is relevant based on their data/requirements. I'll spend more time customizing a topic I know is important in their enviroment. Areas they don't seem to have much interest in I would often leave fairly generic (unless I think they just haven't seen the light yet and need some prodding).

Then I'll have a series of workshop exercises, similar to what you'd see in a Cognos class. These are intended to pull together understanding the data and the functionality of the tool in a meaningful business scenario. Generally I'll get a list from users of the kinds of analyses they'd like to do and flesh those out to include a good cross section of both data and functionality related topics. E.g., something good for charting, something good for illustrating stacked, nested, asymmetrical, etc.

A one-pager that shows all the tool bar icons with a quickie description that can serve as a cheat sheet is also sometimes nice to include.

Nothing really ground-breaking here but hopefully useful in some way :)

[MFGF]

User's don't read user guides which makes the task considerably easier.  :D You can even weave in the occasional insult which will, of course, go unnoticed.

Cool suggestion Lynn! I must remember that trick and suggest it on all my engagements from now on. :)


Snet form my fumblefingers
iPhon 5 usig Tapatalk

[FM]

One of the features i like in Framework Manager, is the feature called "Model Comments". I can, as a BI Modeler, write comments directly in the model on objects.

The only problem is the joins don't have this property... (they can sometimes be quite complex.).

This saves you from creating external documentation about the model.