Documentation of BPM artifacts is optimal when a reader who did not build the app can operate, change and reuse it without reading every script. Practical rules that work in teams:
- Document the "why" in the artifact, the "how" in the model: the BPD's documentation field states the business purpose, owner, SLAs and the events that start / end it; each activity's documentation says what it decides and which system it touches; scripts get a one-line comment per block. Anything that cannot be seen in the diagram (correlation keys, retry behaviour, assumptions about data) must be written down.
- Toolkit artifacts always: every service, business object and coach view meant for reuse has its documentation filled (inputs, outputs, side effects, example) - that is what appears in the designer when someone picks it.
- Snapshot notes: the snapshot description carries the change log ("2.3: added credit check, new EPV creditLimit, needs env var crmUrl"); the release manager reads only this.
- Naming beats documentation: verbs for services ("Get customer", "Validate order"), nouns for BOs, a prefix per toolkit; a consistent naming standard removes half of the need for text.
- Do not document: what the diagram already says ("this gateway checks the amount"), generated artifacts, and transient playback services.
When: while building - the documentation fields are part of the definition of done for an artifact; a review checks them like code. Retrofitting documentation on a finished app is the expensive way. The design documents outside the tool (solution architecture, integration contracts, environment configuration) are separate and stay in the wiki / repository with the twx exports; link them from the process app's documentation field. A useful yardstick: a new developer should be able to explain the process to the business analyst after reading the BPD and its activity documentation - if they need the scripts, documentation is missing.
References