Best way to document a mapping

Question

Is there a way to print a mapping so it displays the operator, name and description in a graphical form showing the links? I'm after a way to document the mapping which makes use of the description information.
Any comments or suggestions on how to document the mapping (get an overview of what's being done) before looking at the detail of each operator.

Answer 1

If you mean "document it in a printable way" - I haven't found a really good way to do that yet. But if you mean "document it so that another developer can go through the map (in OWB) and understand it", I'd offer the following ideas:
1. When you create the mapping - it prompts for both map name and a description. This is the correct place to put mapping overview information.
2. p.s. #1 you can view from inside a map by right clicking on an empty spot within the map and choosing properties
3. Every operator in a mapping has a description box you can get by double clicking on it. I fill these out for operators where it's not readily apparent what's going on. For things where it's perfectly straight forward - don't bother. No sense wasting time / money on documenting something that is self-apparent.
4. Name the operators in a map something meaningful. SET_OPERATOR_1 means nothing to me. MINUS_FIND_CHANGED_RECORDS does.
5. Name ALL input groups in ALL operators. Yes, this will add a few minutes to the development time, but it pays back a thousand fold when you need to maintain the map. Using my example above, MINUS_FIND_CHANGED_RECORDS doesn't mean much if the groups within it are called INGRP1 and INGRP2. It's readily apparent what it means if the input groups are called INCOMING_DATA_FROM_SOURCE and EXISTING_DATA_IN_DW.
6. Don't allow coders to "hide" functionality within an operator. Here's what I mean - on a JOINER operator, you can code filters as part of the JOIN condition (for example:
TABLE1.COLUMN1 = TABLE2.COLUMN2 and TABLE1.COLUMN1 >= 1000
This makes it impossible for someone to easily see what the filter is. Just glancing at the map, you think all records are flowing through. Instead, force them to add a filter operator first (FILTER_REMOVE_SMALL_ACCOUNTS), and then ONLY have the join criteria in the JOINER.
7. Don't allow coders to hit the "Auto Layout" button. This takes a nice, easy to read map and re-locates everything into a mess.
8. Try not to allow any PL/SQL packages to be used. The goal of using OWB is to put everything in a graphical interface. Embedding PL/SQL processes just creates "black boxes". Obviously, I understand this isn't always possible....
Long and short, quite truthfully, a well constructed OWB map should be something you can look at and figure out high level what it's doing (with low level comments on any operators that need additional explaining) - with no other documentation needed. And at the point that a mapping becomes too complicated to follow this way...then the mapping is trying to do too much, and you need to simplify it and have a second mapping.
Obviously my opinions, but I've been doing OWB for a long time now...and I don't think there's any map I've written during that time that I (or even someone else) couldn't go back and EASILY figure out what it's doing - i.e. shouldn't need to spend 30 minutes to figure it out.
Hope this helps,
Scott