What goes where
When something new needs writing down, four questions say whether it belongs in the process, in an extension, in whatever starts runs, or in the catalog.
A process document is the one place that says how the work is done. That only stays true if everything that changes the work goes into it, and everything else stays out. Ask the four questions in order and stop at the first one that answers yes.
-
Does it change the work?
Who does a step, the order of the steps, which steps a person must sign, where the work goes back, what passes between steps, what a run is handed and what a run leaves behind. Anything that changes one of these goes in the process document, where its owner can see it, version it and sign it.
Goes in: the process document
-
Would a person running it from the page need it?
If yes, it goes in the process document too. If only software needs it, and it is the same for every run, it goes in an extension: an optional part with its own published definition, which a runtime that does not know it simply ignores.
Goes in: an extension
-
Is it the same for every run?
If it changes from one run to the next, it is not part of the process. It is something a run is handed. Saved answers and saved settings for common uses belong to whatever starts runs.
Goes in: whatever starts runs
-
Is it about finding or showing the process?
Then it belongs in the catalog. The catalog copies every field it shows from the process document, so a field it needs and the document lacks is added to the document's header.
Goes in: the catalog, copied from the header
Where some real cases went
| The thing | Where it went | Which question decided it |
|---|---|---|
| What a run is handed when it starts, and which items it cannot start without | The process: carries: under the trigger | 1. A run that starts without what it needs is different work. |
| Approving a step on the first run of a new version | The process: an approval holds on every run | 1. Skipping a signature changes who signs. |
| Which organization's process this one was copied from | The process: from: | 2. A person adopting a copy needs to know where it came from. |
| What a form calls each field and what it says under it | An extension: start-form | 2. A person reads the list of items and needs no form. |
| The type of each handoff, and how one is converted for the next step | An extension: typed-handoffs | 2. The handoff's words are enough for a person. |
| Saved settings for a common use, such as investor research | Whatever starts runs | 3. Settings change from one use to the next. |
| A test: what a test run is handed, how its approvals are answered, and what must be true at the end | Beside the process: a test case (section 21) | 3. It differs from one test to the next. |
| A finished example of what a run produced | The catalog, copied from example: | 4. It helps a reader choose the process, not run it. |
The first question is the one that matters. Calling something a setting, a feature or an extension does not move it out of the process if it changes the work. A setting that skips an approval is a change to the process, and it belongs where the owner signs.
The rules behind this page are in section 20.1 of the specification.
Next: The specification