Project documentation / Team wiki / Knowledge management
Project documentation guide: specs, decisions, and runbooks
Create project documentation people can use: clear briefs, decision records, tested runbooks, task links, permissions, version checkpoints, and maintenance rules.
At a glance
Useful project documentation answers a reader’s actual question and stays connected to implementation. Give each page a purpose and owner, link it to related work, record important decisions, test procedures, and update affected documents whenever behavior changes. Use permissions and deliberate publishing to match the intended audience.
Project documentation is the shared record of what a team is building, why it made important decisions, and how the resulting system should be used or operated. It is most useful when a reader can find the answer, understand whether it is current, and follow its links back to the relevant work.
This guide explains how to build that record with Leera Documents. It includes practical structures for briefs, decision records, and runbooks, plus a maintenance process that keeps documentation connected to change. The templates are suggested team practices, not mandatory fields in the application.
Start with the reader’s task
Before creating a page, write the question it should answer. “What are we trying to improve?” needs a different document from “How do I restore the service?” A page becomes difficult to use when it tries to serve every reader at once.
Diátaxis distinguishes tutorials, how-to guides, reference, and explanation according to reader needs. That distinction is a useful starting point for organizing knowledge. A new teammate learning a workflow and an experienced operator looking up a configuration key should not have to navigate the same long narrative.
| Reader’s need | Useful document | What to prioritize |
|---|---|---|
| Understand a proposed change | Project brief or specification | Problem, intended behavior, constraints, and unresolved questions |
| Understand a past decision | Decision record | Context, chosen approach, and consequences |
| Perform an established operation | Runbook or how-to guide | Prerequisites, actions, verification, and recovery |
| Look up exact behavior | Reference page | Precise definitions, options, and version context |
| Learn a workflow | Guided introduction | A safe example and a clear learning sequence |
Give the page a title that makes this purpose obvious. “Expired invitation recovery: specification” is easier to recognize than “Onboarding notes v2 final.” A meaningful title also helps someone sharing the link explain why it matters.
Write a project brief that supports decisions
A brief should establish enough shared understanding to decide what work belongs in the project. Begin with the observed problem and intended outcome. Explain whose experience changes, what evidence motivated the work, and what constraints the team already knows.
Use this suggested structure:
- Problem and affected users.
- Intended outcome and how it will be evaluated.
- Proposed scope and explicit exclusions.
- Important behavior and acceptance criteria.
- Dependencies and constraints.
- Open questions and decision owners.
- Links to implementation and verification work.
For an invitation recovery project, the brief might explain that expired links currently leave users without a clear next step. It can specify the intended recovery message while leaving the token invalidation policy as an open question until the responsible people decide it.
Avoid filling empty sections with speculation to make the brief look complete. “Not decided: whether a replacement invalidates earlier links; owner: product and engineering” is more useful than an invented rule that later becomes an accidental requirement.
Keep supporting research separate when it is long. The brief should link to evidence while remaining a usable entry point for the people planning the work.
Connect the document to implementation
A specification helps delivery when people can move between the explanation and the work it describes. Link the relevant issues, and put a reference to the document where someone implementing or testing the change will see it.
In Leera, selected text can become a Planner task through the formatting toolbar. The selection becomes the task title and is replaced by a linked issue. This is a useful way to turn an agreed action into work while keeping its original context nearby.
Review the resulting task before relying on it. A selected phrase may need a clearer title, an appropriate project, a description, and acceptance criteria. The document-to-task action does not mean every important detail from the surrounding page has automatically become a complete implementation specification.
Prefer links over repeated copies. If the same rule appears independently in five issue descriptions, a change requires someone to find and reconcile all five. Keep the authoritative explanation in a clear location and use issues to capture the work and its current status.
At implementation review, compare the resulting behavior with the specification. Either align the implementation or update the agreed specification and explain the decision. Do not let a document remain authoritative by title while its content quietly becomes historical.
Record the decisions people will ask about later
Some decisions matter long after their associated ticket closes. Capture the ones that affect interfaces, operating responsibilities, significant dependencies, or important product behavior. The purpose is to preserve reasoning that a future teammate cannot reconstruct from the final code alone.
Michael Nygard’s architecture decision record proposal describes short records focused on a decision, its context, status, and consequences. When a decision is replaced, retain the old record and point to the replacement so the history remains understandable.
A practical example might record why an invitation replacement invalidates previous links. Explain the behavior selected, alternatives considered, and consequences for users and implementation. If a later product requirement changes that rule, write a new decision and link both records.
Keep the language direct. “The team chose X because Y, accepting Z” is easier to evaluate than a page that lists alternatives but never states the decision. Include drawbacks and operating costs, since those often explain why the decision is revisited later.
Distinguish proposed decisions from accepted ones. A comment from one reviewer may be a useful suggestion without representing agreement from the people accountable for the behavior.
Build runbooks around verifiable actions
A runbook should help an authorized person perform an operation under realistic conditions. Begin with the situation in which it applies and the prerequisites needed to use it. Name the environment and version assumptions, required access, and signs that the procedure is appropriate.
For each stage, include the intended result and how to check it. A command without an expected observation leaves an operator guessing whether it worked. Explain when to stop and where to find help if the observed state differs.
| Runbook section | Questions to answer |
|---|---|
| Purpose | What problem or operation does this procedure address? |
| Prerequisites | Which access, files, environment, and version are required? |
| Procedure | What actions should the operator take, in what order? |
| Verification | Which observations establish that each critical action worked? |
| Recovery | What can be reversed, and which decision needs escalation? |
| Ownership | Who maintains the procedure and when was it last exercised? |
Test the runbook in a suitable environment with someone who did not write it. Record unclear steps and missing prerequisites. For a self-hosted service, keep the recovery procedure and required access available outside that service; an unavailable workspace cannot serve its own only recovery instructions.
The self-hosting guide gives an example of why operational detail matters: a database dump alone does not provide all the keys, configuration, and files needed for a complete Leera recovery.
Organize pages without building a maze
Start with a small set of collections that reflect how the team looks for information. A project may need a brief, decisions, specifications, and operations references. A broader workspace may also need shared onboarding or team agreements.
Use consistent naming within each collection. Include the subject and document purpose rather than relying on an author’s initials or an arbitrary sequence of folders. Keep the current entry point obvious and link to archived material when history is relevant.
Leera provides collections, favorites, recent documents, and version history. Use favorites for the pages an individual needs often, while maintaining a shared structure that does not depend on everyone copying one person’s personal organization.
Occasionally test navigation with a real question: ask a teammate to find the current invitation policy or the deployment recovery procedure. Observe where they look and which page they mistake for the answer. This reveals confusing titles and duplicate entry points more directly than reorganizing collections by preference alone.
Use versions and permissions deliberately
Autosave and a reviewed checkpoint serve different purposes. Leera autosaves the current document and supports saved versions in history. Save a version at a meaningful review point so the team can inspect the accepted state later.
When restoring a saved version, Leera preserves the current version first. Restoration changes the document content; it does not undo implementation work or decisions in other systems. If a rollback creates a mismatch with the product, explain that mismatch and assign the follow-up work.
Review access according to the page’s purpose. Leera combines document permissions with inherited collection permissions, and owners can grant viewer or editor access. Owners can lock a page to pause editing. A title containing “approved” or “private” is not a substitute for the corresponding process or access setting.
Include access in onboarding and role changes. A person may need a specification to implement a task but not the credentials referenced by an operating procedure. Keep sensitive material in the team’s designated secure location and link to its access process where necessary.
Treat public publishing as a separate review
Leera can publish a selected document as a public read-only page. Review the displayed content and attachments before sharing that link. Check screenshots, copied logs, customer examples, internal URLs, and comments embedded in the document text.
Other workspace pages retain their own access rules, but a public reader can still see whatever the published page itself reveals. Avoid assuming that an attachment is harmless because it was created for an internal audience.
Before publishing, verify that the page’s instructions apply to the public product and current behavior. Internal experiments, planned features, and administrative shortcuts can become misleading when presented as general user guidance. Identify the owner responsible for updating or unpublishing the page later.
When public access is no longer intended, unpublish the page. Also review any external pages that linked to it, so users can find the current replacement instead of a dead end.
Use AI to improve drafts while preserving meaning
Leera’s inline AI actions can help improve writing, change tone or length, translate, summarize, explain, or simplify a selected passage when an appropriate provider is configured. Review the suggestion before accepting or inserting it.
Ask for a specific improvement. “Shorten this procedure while retaining every prerequisite and verification step” gives the reviewer a clearer goal than “make this better.” Compare the result with the original and the actual workflow.
Be especially careful with exact commands, configuration keys, product limitations, and policy statements. A fluent rewrite can change a condition or remove an exception. For translations, verify product names and controls that users must locate in the interface.
AI can also identify missing sections or unresolved questions, but it cannot establish that a document matches the implementation without evidence. The owner remains responsible for checking source material and recording the reviewed result.
Make documentation updates part of the change
Add a documentation impact check to work that changes behavior. The review should cover the affected specification, guides, references, screenshots, examples, and operating procedures. Public changes may also affect pricing explanations, metadata, structured data, and links that describe the product elsewhere.
Use a concrete trigger: if a control moves, check the instructions and screenshots that point to it; if a permission changes, update access explanations; if a configuration key changes, update installation and recovery references. The person making the change should identify affected material, with the document owner reviewing meaning where needed.
Record either the updates made or the reason no document change is needed. This keeps the check useful without demanding a new page for every small edit. Supplement change-driven updates with occasional reviews of high-use and high-consequence documents.
Begin with one active project. Give its key pages clear purposes and owners, connect them to the work, and test whether another teammate can use them. Expand the structure as actual reader needs emerge.
Frequently asked questions
What documentation does a software project need?
Start with a brief explaining the problem and outcome, specifications for important behavior, records of significant decisions, and runbooks for operations people must perform. Add learning and reference material when readers need it. The right set depends on the work and its consequences.
How can Leera documents connect to project tasks?
Select text and choose Task from the formatting toolbar. Leera uses that text as a task title and replaces the selection with a linked issue. Review the resulting task and add the project context and acceptance criteria it needs.
What is the difference between autosave and a saved version?
Autosave preserves the current document. Save version creates a checkpoint in history. Leera supports previewing and restoring saved versions, with the current version saved first when a restoration is performed.
Does publishing a Leera document share the whole workspace?
Publishing makes the selected document a public read-only page, including its displayed content and attachments. Other pages keep their own access rules. Review the page before sharing and unpublish it when public access is no longer intended.
How should teams keep documentation current?
Include a documentation impact check in relevant work. Changes to behavior, permissions, configuration, pricing, or deployment should prompt review of the affected guides, screenshots, references, and public claims. Assign an owner and record what was checked.