Technical documentation

The whole argument for diagrams in Confluence rather than in a design tool is proximity: the diagram sits with the explanation, and both are edited by the same person at the same time.

That is also why text languages work so well here. A diagram that changes in the same edit as the paragraph stays consistent with it.

#When to draw one

• API and integration documentation.

• Data model documentation for people writing queries.

• Any explanation currently carrying the phrase "see the attached diagram".

#What is on the diagram

#A worked example

A lifecycle diagram, which belongs beside the status field it documents:

The source, which you can paste into a new diagram and edit:

stateDiagram-v2
  [*] --> Draft
  Draft --> Submitted: submit
  Submitted --> InReview: picked up
  InReview --> Changes: request changes
  Changes --> Submitted: resubmit
  InReview --> Approved: approve
  InReview --> Rejected: reject
  Approved --> Published: publish
  Published --> Archived: archive
  Rejected --> [*]
  Archived --> [*]

#A few things that catch people out

• Keep the diagram in the same page as the explanation, not in a diagrams space.

• A diagram that contradicts the text is worse than no diagram. Update both in one edit.

• Published documentation keeps diagram links working. See Integrations.

#Related

Diagrams next to the words they explain.