Guides
34 guides on documentation. Practical writing from the team building Atlas, useful whether or not you buy anything.
The test of a working paper file is whether a competent person who was not there can reach the same conclusion from it. Most files fail that test comfortably.
The architecture diagram, the process map, the org chart: each is drawn once in a separate tool, admired briefly, and then quietly diverges from reality. Diagrams go stale not because people are careless, but because they live too far from the work they describe.
Teams use "runbook" and "playbook" interchangeably and then wonder why their documentation is either too rigid or too vague. The words point at genuinely different tools.
The most expensive meetings are the ones where you re-decide something you already decided, because nobody wrote down why. A decision log is the cheapest insurance against that.
A knowledge base is only valuable if it is trusted and current. This guide compares the strongest options fairly, whether you need internal docs or a public help center.
Confluence holds the documented knowledge of a company; Atlas runs the work that knowledge governs. Connecting them keeps a decision recorded on a page from being disconnected from the task it should trigger, and keeps the plan in Atlas anchored to its living specification in Confluence.
Documentation is not one thing. A system that scales separates the reference material that must stay current from the decisions that are frozen in time: and knows where each lives.
A knowledge base succeeds or fails on two things: can people find the answer, and can they trust it. Everything else is detail.
Most company wikis die the same way: a burst of pages, no ownership, and slow decay into a graveyard nobody trusts. Building one that lasts is mostly about maintenance, not creation.
Confluence is where many engineering and product teams document, and diagrams are central to that. This guide covers the practical ways to add diagrams that stay accurate as systems change.
Notion is where many teams keep their knowledge, but it has no real diagram editor. This guide covers the practical ways to get good, maintainable diagrams onto a Notion page.
A wireframe shows structure, but structure alone leaves questions. Annotations answer them: carrying the behavior, rules, and intent that the boxes cannot, without cluttering the design.
Confluence is where a lot of team knowledge lives, and diagrams make it far clearer. The question is whether your diagram stays current with the system or quietly describes last quarter's.
A diagram in a Notion page can be a living picture that updates itself or a static image that quietly rots. Knowing the difference (and choosing on purpose) is the whole game.
A static diagram tells you one fixed thing. An interactive diagram lets you explore (click through to detail, hover for context, watch live data change) turning a picture into something you use.
Pasting a diagram image into a wiki freezes it the instant you export. Embedding the live diagram instead means the version on the page updates whenever the source does: no re-export, no drift.
A REST API looks simple as a list of endpoints and complicated the moment you draw the calls, auth, and errors together. Diagramming it exposes the design before clients depend on it.
You have inherited a database with a hundred tables and no documentation. Reverse-engineering it into a diagram is how you turn an opaque schema into a map you can actually navigate.
A correct schema diagram nobody can read is a failure. The skill is not just showing every table and key, but laying them out so the structure is obvious at a glance.
A system architecture diagram answers the question every engineer asks first: how does this fit together. Doing it well means choosing the right level, the right notation, and a way to stay current.
The difference between a cloud diagram people trust and one they ignore is a handful of habits: consistent grouping, honest notation, the right level of detail, and a plan for staying current.
D2 is a newer diagram-as-code language designed for readability and good-looking output. This guide covers its clean syntax for shapes, connections, containers, and styling.
PlantUML lets you write a diagram as a few lines of text and get a rendered UML diagram back. This guide covers the syntax, the diagram types, and how to make it part of a workflow that stays current.
A diagram that only works if you can see it perfectly excludes a real share of your audience. Making diagrams accessible is not hard, and it usually makes them clearer for everyone.
Code has version control; diagrams usually do not, which is why they drift and no one knows who changed what. This guide covers making diagrams as trackable as the code they describe.
A diagram is a technical writer's most powerful tool for the ideas that resist prose. Used well, it replaces confusion with clarity; used carelessly, it adds one more thing to maintain.
Diagrams drawn by hand drift from the code they describe. Generating diagrams from the source keeps them honest: this guide covers the main approaches and their trade-offs.
Sequence diagrams are the sharpest tool for designing an API, because they force you to think about the full conversation (including the failures) before you build it.
The genius of C4 is its four zoom levels. This guide goes deep on each one: what belongs there, who reads it, and the mistakes that blur the boundaries between them.
There is no single "architecture diagram." There is a toolbox of diagram types, each answering a different question. Knowing which to reach for is half the skill.
The C4 model is the most useful convention for architecture diagrams because it solves the one problem that ruins most of them: mixing abstraction levels. Here is how it works and how to apply it.
A good architecture diagram is not decoration for a slide deck. It is a tool for making decisions and onboarding people faster. This guide shows you how to draw one that stays useful.
Mermaid inside Markdown means diagrams that live in your docs and update with a text edit. Here is how to use it across the big platforms.
Diagram-as-code treats diagrams like source: written in text, versioned in Git, reviewed in pull requests, and never out of date.
Ready when you are
Atlas brings tasks, projects, CRM, contracts, e-signature, PDF tools, and analytics into one workspace. Start free.