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?
- What is the minimum documentation set for a business application?
- What should a runbook contain?
- How much documentation is enough?
- How to build the minimum documentation set
- How do you know the documentation is working?
- Where AI fits
- What delivery record exists, and what does not
- Alternatives: other ways to keep an application maintainable and how to choose
- Limits of this guide
- Frequently asked questions
- Next step
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
-
List who will read it
Name the support team, release owner and any partner, and the tasks each must do without help.
-
Write the system overview and contacts first
One page: purpose, users, business owner, technical contacts and incident contacts.
-
Draw the context and container diagrams
Mark every external integration and data store.
-
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.
-
Build the configuration and access inventory
List settings, accounts, certificates and third-party services with owners and renewal dates.
-
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.
-
Run the stranger test
Give each document to a person who did not write it and fix every step where they get stuck.
-
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.
- Available capability
AI-drafted runbooks under human review
Drafted documents are tested by a person before use; not yet tied to a published support case.
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.
Related services and solutions
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
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
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
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.
Discuss a project
Netbase JSC helps organizations design, build, modernize, and operate digital products and AI-enabled business systems.project@netbasejsc.com
+84 937 869 689
91 Nguyen Chi Thanh, Dong Da, Hanoi, Vietnam
Get in touch
Tell us what you want to build, modernize, or operate.