In the previous article, we explained that while workflow diagrams show what happens, they do not explain the underlying rationale; consequently, the design becomes dependent on a single app administrator.
This article addresses how to prevent that. You don’t need any new tools. Here are two evaluation axes for properly using the description fields available in Questetra BPM Suite.
Axis 1: Separating Identification from Explanation
First, let’s look at the difference in roles between names and notes.
| Field | Role | Visible to Operators? |
|---|---|---|
| Name (App / Step / Data Item Name) | Identification. Distinguishes items when listed or shown in a diagram. | Visible |
| Notes | Explanation. Why it is set up this way and how it relates to other elements. | Not Visible |
Failures typically happen in two ways:
Cramming explanations into names. An example is a step named “Review (Accounting checks amount; 100k+ goes to Director)”. While the information is correct, it makes the workflow diagram unreadable. Names are fields meant for identification—so keeping them short and recognizable is sufficient.
Names fail to function as identifiers. An example is an app with three steps all named “Review”. App administrators cannot distinguish them when tracking settings, and Operators get confused when viewing the workflow diagram. Instead, separate them clearly, like “Accounting Review”, “Manager Review”, and “Final Review”.
The key takeaway here is that Notes are not visible to Task Operators. Therefore, you cannot compensate for an unclear step or item name by relying on Notes. Names must stand on their own as clear identifiers.
The Triad of Data Items
Up to this point, we have focused on Names and Notes, but Data Items feature a third field directed at Task Operators: “Description”. Content written here appears directly beneath that item on the Case form.
| Data Item Field | Role | Visible to Operators? |
|---|---|---|
| Item Name | Identification | Visible |
| Description | Supplementary entry instructions (e.g., “Please enter amount excluding tax”). | Visible (displayed on the form) |
| Notes | Why this item is set up this way. | Not Visible |
It is easy to mix these up. If you write entry guidelines inside Notes, the people who actually need to read them will never see them. Use the Description for info Operators need to read, and Notes for records App Administrators need to keep.
Steps, on the other hand, do not have a separate Description field for Operators—only Names and Notes. Therefore, anything you need to communicate to Operators regarding a step should be documented in the user operational manual or displayed on a Guide Panel within the form.
Axis 2: Separating Present Tense from Past Tense
Next, let’s examine the difference in roles between Notes and Version Notes.
| Field | Content to Write | Editable Later? |
|---|---|---|
| Notes (Step / Swimlane / Data Item / App Admin Notes) | Present tense. Why the current design is set up this way. | Updated whenever the design changes |
| Version Notes | Past tense. What was changed in this version and why. | Cannot be edited after release |
Using the 100,000 JPY threshold example from the previous article, here is how you would apply this:
- In Notes: Write “100k JPY corresponds to approval authority in Article 3 of Purchasing Rules. Update if rules change.”
- In Version Notes: Write “Changed approval authority threshold from 100k JPY to 200k JPY to reflect the April 2026 purchasing rule revision.”
Write both. If you only write one, a successor will lose track of either why it is set up like this right now or when and why it changed.
Crucially, Notes must be rewritten whenever a change is made. If you update a setting to 200,000 JPY while leaving the Notes reading “100k JPY…”, your documentation becomes false from that exact moment.
Version Notes work in reverse—they cannot be rewritten once released. They can only be edited while a version is under development; upon release, the record for that version becomes permanently locked. Because of this constraint, records of past versions remain reliable historical proof.
Guidelines by Field Type
Applying these two evaluation axes across the various Description fields in Questetra BPM Suite yields the following breakdown:
| Description Field | Primary Audience | Content to Write |
|---|---|---|
| Summary | Operators | What this app does in a single sentence. |
| User Manual | Operators | How to use the app: operating procedures and decision criteria for form entries. |
| Data Item Description | Operators | Supplementary instructions for entering that specific item. Displayed directly on the form. |
| Guide Panel | Operators | Instructions covering the whole form or a group of items. Uses a display-only item without an input field, with text written in its “Description” field. |
| Annotation | Anyone viewing the diagram | Diagram reading supplements or highly prominent warnings. |
| App Admin Notes | App Administrators | Overall app design policies, related apps, and assumptions for external system integrations. |
| Step / Swimlane / Data Item Notes | App Administrators | Why that specific element is configured the way it is. |
| Version Notes | App Administrators | What was changed in this version and why. |
Notice how the target audience is clearly divided between Operators and app administrators. Writing operational guidelines meant for Operators inside “App Admin Notes” won’t show up on their task screen. Conversely, placing internal architectural reasoning inside a User Manual will only confuse end users.
What to Write and What NOT to Write
When it comes to Notes, there is one clear general rule: Do not write things that are obvious just by looking at the settings. Only write things that cannot be understood from the settings alone.
Examples of what NOT to write:
- “This data item is required.” — Obvious by checking the required setting.
- “Branches to Director Approval when amount is 100k JPY or more.” — Obvious by checking the branch expression.
- “Deadline is 5 days after token arrival.” — Obvious by checking the deadline setting.
- “This step is handled by Accounting.” — Obvious by checking the swimlane assignment.
Examples of what TO write:
- Why a specific value was chosen
- 100k JPY corresponds to approval authority in Article 3 of Purchasing Rules. Update if rules change.
- Business rule specifies 3 business days. Since deadlines cannot specify business days, set to 5 calendar days to provide a margin.
- Dropdown options are sorted by request frequency. Review at the start of each fiscal year.
- How it connects to external elements
- This item’s value is sent to kintone “Customer Master” in the automated step right before completion. Completing with this field blank overwrites the kintone record with blank data.
- This date is passed to the child App “Contract Renewal Reminder”. The passed value becomes the child App deadline.
- This choice ID maps 1:1 with core system code tables. Adding new choices without updating backend codes breaks the integration.
- What MUST NOT be done
- The case sequence number is inserted into the Title during this “Update Data” step. Bypassing this step leaves the title blank.
- The applicant was intentionally excluded from assignment in this swimlane to meet audit requirements. Do not assign back even if roles overlap.
- Do not reconnect rejection paths before this automated step; executing twice registers duplicate invoices.
- Why an alternative approach was rejected
- Automation was evaluated but abandoned due to excessive edge cases; kept manual intentionally.
- Managing via Choice Master (Add-on) was considered, but kept as fixed choices since updates only occur annually.
- A 3-way branch was proposed, but reduced to 2 branches because operations could not reliably evaluate the third condition.
Simply rephrasing settings provides zero value, despite giving a false sense of accomplishment. Worse, people forget to update rephrased settings when configurations change, quickly turning them into incorrect documentation. The only things worth documenting are insights gained by viewing the system as a whole or context existing outside the App itself.
There is one exception to this rule: change history. An entry like “Changed from 200k JPY in April 2026” cannot be known just by looking at current settings. Nevertheless, do not write this in Notes—because a dedicated place exists for it.
Since Notes are updated with every change, writing history there means it will either get erased during the next update or pile up indefinitely. Record past changes in Version Notes instead. In software development, change history belongs in commit logs rather than inline code comments, for the exact same reason.
Character Limits
Notes (Step, Swimlane, Data Item, App Admin Notes), Summary, Annotations, and Version Notes are all limited to 256 characters. Long-form prose can only be written in the User Manual and Data Item Descriptions—both of which are fields intended for Task Operators.
Notes should be written concisely, around a few lines per element. If information exceeds that length, split it according to audience and scope: place element-specific reasons in the element’s Notes, overall architecture policies in App Admin Notes, and operational instructions meant for Operators in the User Manual.
3 Rules for Sustainability
- Write at the moment you make a change. If you think “I’ll organize the documentation once the app is finished”, that time will never come. Record the reason right then and there when changing a setting. That moment is the only time you truly understand the reasoning.
- Don’t document just to fill blank space. Filling fields with empty phrases like “To obtain approval” is more harmful than leaving them blank. A blank field accurately communicates that nothing was written, whereas meaningless text falsely claims “this is the reason”, causing readers to stop searching. If there is no specific reason worth recording, leaving it empty is perfectly fine.
- Never leave outdated notes unattended. When changing settings, re-read the Notes for that element. If still accurate, leave them; if outdated, fix them. Conversely, do not delete existing Notes without understanding them. If a note seems unclear, verify with the author rather than deleting it—the fact that it’s confusing indicates documentation was necessary there in the first place.
Summary
- Names are for identification; Notes are for explanation. Don’t cram explanations into names.
- Data Items rely on a triad: use “Description” for Operators, and “Notes” for app administrators.
- Notes use present tense; Version Notes use past tense. Document current reasons vs. modification history.
- Do not write things that are obvious just by looking at settings.
- Write at the exact moment you make a change.
What you need is neither a new tool nor elaborate specification documents. It is simply writing a few lines in existing description fields whenever you make changes. The real value shows up after the person who wrote them is gone.
Next Time
In the next post, we will cover building workflow apps using AI. Recording design intent is also a necessary prerequisite for delegating work to AI.
- Preserve Design Intent (Part 3: Delegating to AI) 《Coming Soon》
