Organize activities before choosing shapes
This guide uses an original community exhibition-hall equipment-loan process. An applicant states the purpose, a desk attendant checks availability, an administrator confirms the applicable rules, and staff record handover and return. It is a teaching example, not an implemented approval policy. Deliver an activity table, a responsibility diagram, editable source and a matching presentation export rather than only a screenshot.
Define scope, audience, start, end and authoritative rules. Separate decisions already made in meeting notes from suggestions and unresolved questions. A discussion about emergency borrowing must not silently become permission to bypass approval. Give each activity a stable identifier, owner, input, action, output and next condition. Missing policy belongs in a question list rather than an invented arrow.
Scenario one: turn prose into a reviewable draft
Extract application, availability check, confirmation, handover, return and inspection. Verify who performs each action. Keep nodes focused on a checkable action instead of placing entire paragraphs inside boxes. Normalize role names so two descriptions of the same desk attendant do not become separate actors.
Every decision needs understandable exits. Unavailable equipment may lead to rescheduling or cancellation; incomplete information returns for correction; damaged returns require an exception route. Define cancellation, timeout and duplicate-request handling where the real process specifies them. Mark unknowns explicitly. The example supplies no invented deadline or compensation amount.
Have a process owner walk the activity identifiers through a normal path and two unsuccessful paths before drawing. Ask who knows a step is complete, where its output exists and what enables the next step. If one person both applies and approves, check whether that is intended rather than treating a diagram convention as governance. Deliver the activity table, questions and version record as the basis of subsequent diagrams.
Scenario two: distinguish swimlanes from other project views
A swimlane emphasizes responsibility and handoffs. Choose orientation for the audience and complexity. Put actions in the lane of their actual performer and label meaningful cross-lane transfers. Parallel work differs from sequential approval; specify whether a join requires all branches or one condition. Label rejection in text rather than using red alone.
For the equipment example, the applicant owns submission and correction, the attendant owns availability and physical handover, and the administrator owns the stated rule confirmation. Separate ordinary closure from an exceptional return. Keep node identifiers aligned with the activity table. A lane location is not authorization, and the drawing does not prove that software enforces the process.
Use a timeline for stages and dates and a Gantt view only when dates and dependencies are actually known. Do not infer duration from sequence alone. A turtle diagram can organize process inputs, outputs, resources, methods and measures; it is not an interchangeable approval route. Architecture, sequence, state and entity-relationship diagrams answer different questions. Choose the question before selecting the template rather than placing every relationship in one flowchart.
When people need drag-and-drop maintenance, assess an editable diagrams.net document. Open the actual source in the target editor, inspect connections, save and reopen it. An image or ordinary SVG is generally a display artifact, not a guarantee that the native process structure can be recovered. Retain editable source, display export and matching version information.
Scenario three: maintain Mermaid code and presentation output together
Mermaid is useful for storing structured diagram source alongside documentation. Begin with syntax supported by the destination renderer, stable node IDs and clear labels, then add grouping and style. A subgraph can express grouping without guaranteeing rigid swimlane geometry. Connections outside a group can affect its direction. Strict layout requirements may call for a different editing workflow rather than a promise that one prompt produces exact coordinates.
Render in the real destination and check syntax, fonts, long labels, branches and arrows. Support in one GitHub or documentation view does not establish identical behavior in every Markdown viewer or version. Some environments show code until rendering support is configured, or need an exported image. Record renderer version and export method instead of claiming there are no setup requirements.
For presentation quality, keep actions, decisions and endpoints visually consistent. Shorten labels and put detailed policy in numbered notes. Use text, position and line style as well as color. Inspect grayscale and narrow-screen readability. Shadows or a fashionable palette cannot repair an incorrect edge and should not hide exception routes.
If administrator confirmation moves after availability checking, change the activity table and conditions first, update source and then export again. Check that return edges still reach the intended node. Moving a box without updating its relationships can preserve the old meaning accidentally. Record the changed rule, affected nodes and reviewer so a fifth diagram does not still reference a third-version description.
Verified skill role
The catalog search returned Mermaid-related entries for codebase wikis, site packaging and a particular wiki conversion task. It did not establish the five general-purpose drawing skills named in the original article, so no guessed install links are supplied. Use the official Mermaid or diagrams.net documentation and the actual target environment for the diagram itself. Mermaid's public project and documented interface suit a source-based workflow, subject to version, license and layout checks.
Writing Guidelines fits review of the technical activity descriptions and maintenance instructions: role naming, steps, conditions, artifacts and concrete file references. It needs the draft files and access to its relevant rules. It does not generate a Draw.io file, validate business policy or execute Mermaid. Source evidence, scanning and observed execution remain different signals.
A practical request and acceptance method
Ask: “Convert these equipment-loan notes into an activity table with roles, inputs, outputs and every decision exit. List unconfirmed rules separately. Review that table before producing editable diagram source and a display export. Cover unavailable stock, correction, cancellation and exceptional returns. Do not invent time limits or amounts. Preserve node identifiers and state the destination renderer and untested scope.” This produces inspectable work rather than only an aesthetic target.
Check logic and file behavior separately. Every start should reach an appropriate end, decisions need named exits, handoffs need owners and exceptions must remain visible. Open the source, edit a label, save and reopen to establish actual editability. Compare the export with the source for complete labels, readable fonts and matching content. These are acceptance instructions, not claims that such operations were performed for this article.
Troubleshooting, FAQ and sources
For syntax failures, reduce to a minimal diagram and inspect quoting, special characters and unsupported features. For confused layout, reduce long cross-group connections or split the diagram. If a destination shows code, inspect rendering support instead of rewriting business logic repeatedly. If the diagram conflicts with meeting notes, return to the authoritative rule; the most recently generated file does not automatically win.
Can it be edited? That depends on retained source and the target tool, not just an extension. Can complex flows be wrong? Yes, so preserve activity review and path walkthroughs. Is installation always unnecessary? Browser editors still have access and file prerequisites, and offline environments may need configuration. Is a natural-language change enough? Render again and inspect affected paths.
References are the official Mermaid flowchart documentation and diagrams.net editing guidance, with the original Chinese and English sources retained together. The exhibition-hall scenario is original and includes no fabricated user testimony, installation count or executed drawing result. Deliver activities, unresolved rules, editable source, display output and actual review records, and update them together as the process changes.