Project Documentation: What to Write, Where to Keep It

Good project documentation answers the questions people will ask later, when the person who knows has moved on. Bad project documentation is either missing or so voluminous nobody reads it. The trick is writing the few documents that matter and keeping them where people will find them.

The documents worth writing

Not every project needs every document. For most software and agency projects, this set covers what people actually ask about:

• Project brief — the problem, the goal, who it is for and what success looks like. One page.
• Scope — what is in, what is out and what was agreed. Our guide to project scope management covers this in depth.
• Decision log — significant choices, the options considered and why one won.
• Architecture and data model — how the system fits together, ideally as diagrams. An ER diagram is often the most useful single picture.
• Environments and deployment — where things run and how to release them.
• Release notes — what changed in each release, written for the reader. See how to write release notes.
• Handover notes — what the support team or client needs to run it after you leave.

The documents to skip

Some documentation is written because it feels responsible rather than because anyone will read it:

• Status reports that duplicate what the board already shows.
• Specs that restate every ticket's acceptance criteria in prose.
• Meeting minutes that record discussion but not decisions or actions.

If a document repeats information that lives somewhere more current, link to the source instead of copying it. Copies go stale.

Tired of hunting for docs? See how Flow keeps knowledge linked to the tickets it explains. Get started with Flow →

Where to keep project documentation

Location decides whether documentation gets used. Three rules help:

1. One home per project. All project documentation lives in one space with a predictable structure, not across drives, inboxes and chat.
2. Close to the work. The spec should be reachable from the ticket that implements it, and vice versa.
3. Shareable on purpose. Some documents are for the client, most are internal. Decide which and set permissions accordingly.

Confluence has been the default home for project documentation in many teams for years. It is a capable wiki with strong structure and permissions, and it pairs with Jira as a separate Atlassian product. The friction teams describe is the link between the two: keeping pages and tickets connected takes deliberate effort.

Keep it short, dated and owned

Every project document should show who owns it and when it was last reviewed. Prefer short pages that link to each other over one long document. Use templates so a brief or a decision record always has the same shape; readers learn where to look.

How Flow does it

In Flow, project documentation lives in Verso, the built-in knowledge base, alongside the project's board, timeline and releases. That makes it a practical Confluence alternative for teams who want documentation and delivery in one place.

• Pages linked to tickets both ways — specs, decisions and runbooks stay attached to the work they describe.
• Embedded diagram boards and project timelines — drop a live diagram or the project timeline into a page instead of pasting a screenshot that ages.
• Templates and export — standardise briefs and handover notes, then export to PDF when a client needs a document.
• Database designer — draw your data model as an ER diagram and export the SQL from the same platform as your docs, all within Livex Flow.