There’s a rather interesting theme out there, on Cognoise.
How do you document EP models? And moreover, how do you document changes? Do you change initial project definition after implementing change requests?
This is not a Cognos-only topic. I digged the net for various approaches, but found nothing more or less suitable.
In general, I regard three layers of documentation:
1 Describing future system. That’s Project Concept, System Requirements and so on. They are based on interviews and usually describe system in various level of detail. But they are, in my experience, written before system is created (or in parallel – no big deal).
2 Describing the way system should work to be accepted by Client. That can be test descriptions, test protocols, use cases. It can be an Excel system, possessing the desired functional. Anyway, that layer is for setting the system in production.
3 User Instructions. Screenshots and text, online help, even videos, explaining what to do, and how to do it. Those are written (recorded) while the system is being tested. How to use\scale the system.
Fine. After a project is finished. All three layers (two boxes) of docs are there. And immediately there goes a change request (those start to fall even earlier).
What documentation should be changed? There is an “eagle-view” description — should it appear there? It’s signed, and updating signed System Requirements is bad for your karma. And changing it is rather costy.
Normally it’s sad that the system is 1 layer of accepted docs + all Change Request completed. Hell, no one can possibly understand it that way.
I’m thinking that current set of:
1 Visio for “eagle view” and business-logic
2 Manager Flowcharts for realization detail
3 Wiki for high-level description and some part of user help
4 Bug-tracker for Change-Requests
is not enough. Need an integration tool to glue CR to initial project doc, and to magicaly create up-to-date 1-level docs. Some DocBook for EP, maybe.
And no AIM or ASAP, please, I don’t think they are of use for 2-4 people, usually forming our project teams. And I now about documentation level agreements, that’s just the change requests problem.