Wikis and process diagrams
Document a project by configuring wikis and process diagrams
Two kinds of wiki
| Kind | Content lives in |
|---|---|
| Project wiki | A wiki repository Azure DevOps provisions for you |
| Publish code as wiki | A folder in an existing Git repository |
The second matters more than it looks: publishing code as wiki means documentation is versioned and reviewed alongside the code it documents, so a pull request can change behaviour and its description together. A separate project wiki drifts, because nothing forces the two to move at once.
Mermaid in the wiki
The Azure DevOps wiki supports Mermaid diagrams — sequence diagrams, flowcharts, Gantt charts, class and state diagrams, user journeys, pie charts, requirements diagrams, gitgraph, entity-relationship and timeline diagrams.
Diagrams as text is the point. A Mermaid diagram diffs in a pull request, so a reviewer sees that an arrow changed; an exported PNG shows only that a binary file differs.
What to document
Favour things that are expensive to rediscover: architecture decisions and their reasoning, runbooks, onboarding. Avoid duplicating what the code already states — duplicated documentation is worse than none, because it becomes wrong without anyone noticing.
Primary sources