---
title: "The map, the setup guide, and the decision log: three types of technical documentation"
slug: "map-setup-guide-decision-log-documentation"
primary_keyword: "types of architecture documentation"
search_intent: "framework / educational"
meta_description: "A three-part documentation model that separates current system understanding, onboarding instructions, and historical decisions."
excerpt: "Documentation rots faster when teams treat setup instructions, current architecture, and historical decisions as one document with one update rule."
suggested_internal_links: "/blog/decisions-not-just-drawings, /how-it-works#ledger"
hero_image_brief: "Three distinct document panels: Setup, Map, and Change, each with a different update clock."
cta: "Use Arialine for the living map and decision-linked visual history while keeping setup instructions close to the code."
quality_score: "90/100"
article_number: 28
author: "Andrii"
published_at: "2026-07-15T00:00:00.000Z"
reading_time: "2 min read"
---

A single "architecture document" often tries to serve onboarding, current-state explanation, and historical justification. Those jobs change at different speeds, so the document becomes inconsistent.

> **Direct answer:** Separate technical documentation into three types. The setup guide explains how to run and work with the system. The map explains how the system works now. The decision log explains why important changes were made at specific points in time. Give each type a different owner and update rule.

## The setup guide: operational instructions

The setup guide contains commands, prerequisites, local development steps, tests, and common failures. It should live close to the code because people discover errors while using it.

Update trigger: someone changes the development or deployment workflow, or a new engineer finds a broken step.

A setup guide is successful when a new contributor can follow it without private assistance.

## The map: current understanding

The map explains the present architecture at useful levels. It begins with the broad system and drills down only where additional detail helps a real audience.

Update trigger: a change alters a boundary, dependency, data flow, contract, or ownership model.

The map should be reviewed periodically, but periodic review is a safety net. The main update should happen as part of the change.

## The decision log: historical reasoning

An ADR or decision entry records what the team believed and chose at a moment in time. It should not be updated every time the system changes. Instead, a new decision supersedes or modifies the old one.

Update trigger: a significant decision is accepted.

This immutability is a feature. It lets future readers understand assumptions that may later prove wrong.

## Why separation reduces rot

When all three live in one document, contributors hesitate to edit it. They may need to preserve old reasoning, update current diagrams, and fix setup commands at once. Clear boundaries make changes smaller and safer.

The separation also clarifies status. A three-year-old ADR can still be perfectly accurate as history, while a three-month-old current map may be dangerously stale.

## Connect the three types

A setup guide can link to the map for orientation. The map can link to decisions that explain major components. A decision can link to the map version it changed.

The documents form a graph rather than one giant page.

## Where Arialine fits

Arialine is well suited to the map and visual decision history. The current board shows the present architecture; the version thread and Canvas ledger explain how it changed. Setup commands should remain in the repository or an operational guide.

This positioning keeps Arialine focused and prevents it from becoming a generic documentation dump.

## FAQ

### Where do runbooks fit?

Runbooks are a fourth operational category. They explain how to respond to known conditions and should be tested during incidents or exercises.

### Can an ADR include a diagram?

Yes. Link or embed the exact diagram version that the decision affected.

### Should the map include implementation details?

Only when those details matter to the intended reader. Prefer generated sources for highly volatile detail.