Skip to main content

What are you looking for?

Explore our services and discover how we can help you achieve your goals

Client Workspace

Runbooks and Documentation for Maintainable Applications: The Minimum Set

A maintainable business application needs seven documents: a system overview, architecture views, a decision log, build and release steps, a configuration inventory, an observability guide and runbooks. This Netbase guide gives each an owner, a trigger that forces an update and a test that someone who did not build the system must pass.

Book a solution review See how Netbase runs support

By Netbase Delivery and Quality Desk · Reviewed by David (CEO) · Updated · 11 min read

star

It is for IT managers, product owners and CTOs who own a live application, or are about to receive one from a vendor or hand it to a support partner. Netbase keeps live software running through application maintenance and support and moves ageing systems onto supported technology through legacy modernization, where missing documentation is usually the first risk found.

In this guide

Why do applications become hard to maintain when the code still works?

An application becomes hard to maintain when the knowledge needed to change it lives only in a few people's heads. The code may run for years, but nobody can safely upgrade, move or fix it once those people have left.

The UK Home Office engineering standard on a minimal documentation set for a product states the purpose plainly: document a product to a minimum standard so that new engineers can be onboarded easily and knowledge is not siloed within the team. It asks for a product description with incident contacts, architectural views, a decision log, runbooks for incident support, disaster recovery and maintenance tasks, observability information, and the build, release and deployment processes.

Most teams lack the right few documents kept current, not documents as such. A long wiki written once at launch misleads readers who act on outdated steps.

What is the minimum documentation set for a business application?

The minimum set is seven documents. Each one answers a question someone will ask during maintenance, has one named owner, changes when a specific event happens, and passes a test that proves it is usable.

  • System overview

    Question it answers
    What does this do, for whom, and who do I call?
    Owner
    Product owner
    Update when
    Users, contacts or scope change
    Proof test
    A new engineer explains the system's purpose and users after reading it
  • Architecture views

    Question it answers
    What are the parts and how do they talk?
    Owner
    Lead engineer
    Update when
    A component, integration or data store is added or removed
    Proof test
    A reader traces one user request end to end on the diagram
  • Decision log

    Question it answers
    Why was it built this way?
    Owner
    Lead engineer
    Update when
    A significant technical choice is made or reversed
    Proof test
    A reader finds the reason behind three surprising choices
  • Build, release and rollback

    Question it answers
    How do I ship a change and undo it?
    Owner
    Release owner
    Update when
    The pipeline, hosting or release route changes
    Proof test
    Someone outside the team deploys to a test environment and rolls back
  • Configuration and access inventory

    Question it answers
    What settings, secrets locations, accounts and third-party services exist?
    Owner
    Release owner
    Update when
    A setting, account, certificate or vendor changes
    Proof test
    Every production setting is listed, with no secret values in the document
  • Observability guide

    Question it answers
    Where are the logs, dashboards and alerts, and what is normal?
    Owner
    Support lead
    Update when
    An alert, dashboard or log location changes
    Proof test
    A reader finds yesterday's error rate without help
  • Runbooks

    Question it answers
    How do I do this routine task, or handle this failure?
    Owner
    Support lead, per runbook
    Update when
    The procedure changes, or an incident shows a gap
    Proof test
    A person who did not write it completes the task from the runbook alone

A document nobody has tested is a draft, however long it is.

Keep the decision log short. An architectural decision record captures a single decision and its rationale, trade-offs and consequences; the collection of records is the decision log.

The C4 model describes four diagram levels: system context, containers, components and code. Context and container diagrams answer most maintenance questions; lower levels go out of date fast.

What should a runbook contain?

A runbook is a step-by-step guide for one task with one outcome, written for someone who did not build the system. The AWS Well-Architected guidance on using runbooks sets the minimum as a step-by-step text document that states the desired outcome, the tools and special permissions needed, and error handling and escalation, with a named owner and a central location. It advises validating each runbook by having someone else run it, and updating runbooks through change management as procedures evolve.

For a business application, write one runbook per routine task and per likely failure:

  • Routine tasks. Deploy, roll back, renew a certificate, rotate a credential, restore a backup to a test copy.
  • Likely failures. A payment integration stops, a queue backs up, a scheduled job fails, a third-party API changes.

Each runbook fits on one page: outcome, when to use it, access needed, numbered steps with expected results, what to do when a step fails, escalation, owner and last-tested date. Incident runbooks that a paging alert links to follow the same shape; on-call and incident response for small engineering teams covers how to write those for night-time use.

How much documentation is enough?

Depth depends on how often the application changes, how many teams touch it and whether an auditor reads the documents.

Option What it includes Choose it when Do not choose it when
Lean set The seven documents, each one to three pages, runbooks only for routine tasks and failures that have happened One team owns the application, it changes monthly or less, no regulator reads the documents A partner will take over support, or the application holds payments or personal data at scale
Full set The seven documents plus data model notes, integration contracts and runbooks for every alert Support is split between companies, several teams release, or a handover is planned Nobody is assigned to keep the extra documents current
Regulated set The full set plus evidence of reviews, access approvals and tested recovery An auditor, insurer or customer security review asks for proof The extra evidence would only be produced once for a sale and never refreshed

Choose the smallest level that passes your proof tests.

What should you not document?

Skip what the code, the tracker or the tools already record. Do not copy code comments into a wiki, describe every class or write runbooks for failures nobody can predict, and never paste passwords, keys or tokens into any document; the inventory records where each secret is stored, not its value.

How to build the minimum documentation set

  1. List who will read it

    Name the support team, release owner and any partner, and the tasks each must do without help.

  2. Write the system overview and contacts first

    One page: purpose, users, business owner, technical contacts and incident contacts.

  3. Draw the context and container diagrams

    Mark every external integration and data store.

  4. Record the build, release and rollback route

    Write it as a runbook and test it by having someone outside the team deploy to a test environment.

  5. Build the configuration and access inventory

    List settings, accounts, certificates and third-party services with owners and renewal dates.

  6. Write runbooks from real work

    Start with the routine tasks of the last three months and the incidents of the last year, one page each.

  7. Run the stranger test

    Give each document to a person who did not write it and fix every step where they get stuck.

  8. Tie updates to change

    Add "documents updated" to the definition of done for releases and incident reviews.

How do you know the documentation is working?

Documentation works when people use it under pressure and it gives the right answer. The clearest sign is a new engineer or support partner who deploys and handles a common ticket from the documents alone. Incident reviews that find a runbook missing or wrong show where to write next, and questions only one person can answer show knowledge still siloed.

The same documents make other maintenance work safer. A bug-fix workflow with regression tests relies on the build and release runbook, and a split of L1, L2 and L3 support tiers relies on knowledge articles and runbooks that a first-line team can follow.

Where AI fits

AI helps most with the first draft and with spotting drift. A model can draft an overview or a runbook from the repository, deployment scripts and past tickets, summarise the history behind a decision from commit messages, and flag documents whose steps no longer match the pipeline. Engineers still check every drafted step against the running system, run the stranger test, decide what is worth documenting and keep secrets out of every prompt and document. Netbase works with the major commercial and open-source AI tools and models, chosen per project.

What delivery record exists, and what does not

Netbase runs, maintains and upgrades what it builds, remotely and alongside the client's in-house team, under an agreed support scope, with response targets set per contract. Engagement models include on-demand support and fully managed delivery, and most Netbase projects are delivered on fixed-price contracts; milestone-based, monthly team retainer and KPI-linked models are also offered.

Progress is tracked in Jira, Redmine, Trello or GitHub, where clients can check it at any time, source code is managed in GitHub, and the project workflow ends in delivery and maintenance under contract. Delivery teams combine business analysts, project managers, solution architects, developers, QA and UI/UX. Published security practices include role-based access control, secure code review and disaster recovery.

Netbase delivered the Netztech migration from Magento 1 to Magento 2; see the Netztech record. No documentation volume, support result, onboarding time or saving is published, and none is claimed here.

Alternatives: other ways to keep an application maintainable and how to choose

  • Rely on the original team. Keep the people who built it and document little. Choose it only for a short-lived or low-risk internal tool; it fails as soon as one person leaves.
  • Documentation as a one-off handover project. Write everything at the end of a contract. Choose it when a vendor change is planned, and follow a staged transition and knowledge-transfer plan so the documents are tested during an overlap.
  • A structured documentation framework. Diátaxis separates four forms of documentation: tutorials, how-to guides, technical reference and explanation. Choose it for larger products with many readers; for one application, the seven-document set is usually enough.

Limits of this guide

  • The seven documents are a minimum for one business application, not a full documentation standard for a product company.
  • Regulated sectors may require specific documents and retention periods; check them with your compliance owner.

Plan the next step with a Netbase consultant

Frequently asked questions

Ask for the seven documents of the minimum set as contract deliverables, and accept them only after someone outside the vendor's team has deployed and run a routine task from them.

A runbook is one kind of documentation: a step-by-step procedure for one task with a defined outcome. The rest of the set explains what the system is, how it is built and why; runbooks tell a person exactly what to do.

Give every document one named owner, usually the product owner for the overview, the lead engineer for architecture and decisions, and the release or support lead for operational documents. Ownership by a whole team usually means nobody updates it.

Test a runbook whenever its procedure changes, after any incident that used it, and in a regular review. A person who did not write it follows it and must reach the stated outcome.

Next step

If you own an application that only a few people can safely change, or plan to hand it to a support partner, and want its documentation gaps listed before you decide, book a solution review.

AI-assisted legacy modernization that keeps your orders and data safe AI-assisted legacy modernization that keeps your orders and data safe

Netbase provides legacy application modernization services for commerce and operations teams to move ageing platforms, such as Magento 1 stores, onto supported technology without losing orders, customers or data. AI speeds up code analysis and data mapping; every migration runs on a written, human-approved plan with rehearsal, staged cut-over and rollback, proven by Netztech's move to Magento 2.

Learn More
line
Application maintenance and support for live web, mobile and business software Application maintenance and support for live web, mobile and business software

Netbase maintains and supports software that is already live: web platforms, online stores, mobile apps, ERP and CRM systems and internal tools, including software another vendor built. We take it over after a code and environment review, then fix defects, keep frameworks current, monitor it, make small changes and report monthly, under service levels agreed in your contract.

Learn More
line
Multi-vendor marketplace development: vendors, catalog, payouts and AI search on one platform Multi-vendor marketplace development: vendors, catalog, payouts and AI search on one platform

A multi-vendor marketplace is a commerce platform where many independent sellers list, sell and get paid through one storefront. Netbase's marketplace solution covers vendor onboarding, a shared catalog, split payments and payouts, with AI for search, listing enrichment and fraud checks. For an EU fashion-tech marketplace, Netbase's work grew gross merchandise value (GMV) and cut vendor onboarding time.

Learn More
line

Work with Netbase remotely

Every Netbase engagement is delivered remotely, so clients in any country and any industry can work with us; Netbase has worked with clients in 80 countries. Contracts and invoices are issued by Netbase JSC, and payment is made by bank transfer to Netbase JSC's company account or PayPal Business. Talk to the CEO, Huy Nguyen (David), on WhatsApp or by email.

Contact Netbase

Discuss a project

Netbase JSC helps organizations design, build, modernize, and operate digital products and AI-enabled business systems.
Project enquiries

project@netbasejsc.com

WhatsApp

+84 937 869 689

Office address

91 Nguyen Chi Thanh, Dong Da, Hanoi, Vietnam

Get in touch

Tell us what you want to build, modernize, or operate.

Tell us what you want to build, modernize, or operate.

Contact Netbase