Working with Documentation

Documentation is most useful when it sits next to the thing it explains. Legend keeps docs connected to the Landmarks and Agents they relate to, so context is never more than a click away.

Attaching documentation

Link a document to the Landmark it describes, such as a runbook to its service or a policy to the process it governs.

Create a Landmark of type Documentation, or open an existing one.
Point it at where the document actually lives, so people reach the canonical version.
Link it to the Landmark it describes.
Save. Anyone who lands on that entity finds the relevant reading right there, instead of searching a separate wiki and hoping it is up to date.

Keeping documentation current

The best documentation is the documentation people actually maintain. Because docs are attached to entities that owners already visit, updates tend to happen where the work happens.

Treat reviewing a Landmark as a natural moment to check that its documentation still matches reality.
When ownership changes, confirm the new owner knows which documents they now maintain.
Remove or update links to documents that have moved or been retired.

Making docs discoverable

Documentation attached to the map shows up in search and in the relationships around each entity. That means people find the right guide by following the map they were already using, rather than needing to know the exact title in advance.

Screenshot: a service page with its attached runbook shown in the documentation section, one click away from the service itself.