When we take over an app, we usually find one of two situations. Either there’s no documentation at all and all the knowledge about the project lives in one developer’s head. Or there’s a thick specification from the start of the project describing an app that was never actually built. Either way, the new team spends its first weeks reconstructing knowledge, and the app owner pays for it.
Good technical documentation isn’t long. It’s a handful of short documents that answer the questions asked with every change of vendor, every release and every outage. Below we describe what it should include and how to check whether what you have is any use at all.
Documentation that doesn’t help
Before we get to what’s worth having — three kinds of documents that rarely help with maintenance:
- A functional specification from the proposal stage. It describes what was supposed to be built, not what actually works. After a year of development it diverges from the app in many places.
- Auto-generated descriptions of classes and methods. They say what the code does, which you can see in the code itself. They don’t say why it works the way it does.
- Documentation nobody updates. An outdated guide is worse than none, because the new team wastes time on steps that stopped working long ago.
The documents that are worth something describe what you can’t quickly read from the code: how to build the project, where the accounts are, how to ship a release and why non-obvious decisions were made.
The minimum documentation for a mobile app
Document The question it answers Setup guide How do you build and run the app on a clean machine? System map What does the product consist of and what talks to what? Account and access register Where are the accounts, who owns them, who has access? Release process How do you ship a new version, step by step? Deadline register What expires, and when? Technical decisions Why was something done in a non-obvious way? Key flows and integrations How do sign-in, payments and notifications work? API description What endpoints does the backend have and how do they change? Known issues and technical debt What do we know is wrong, and what’s the plan?Setup guide
The most important document and the one most often missing. It should cover:
- tool versions: JDK, Android Studio, Xcode, and Flutter or Node.js where relevant,
- where to get configuration files that aren’t in the repository, such as
google-services.json, and who issues them, - how to switch environments — test and production,
- how to run the app on an emulator and on a phone.
Secrets, passwords and keys don’t belong in the documentation or the repository. The documentation only says where they’re stored and who can share them.
System map
One diagram and a short list: the Android app, the iOS app, the backend, the admin panel, the database and every external service — payments, maps, notifications, email, analytics. For each service: what it’s for, whose account it’s on and where the provider’s documentation is. The list also comes in handy for keeping track of deprecated SDKs and APIs.
Account and access register
Google Play Console, App Store Connect, Apple Developer, Firebase, the cloud, the domain, DNS, the payment gateway, the SMS and email provider. For each account: who owns it, who has admin access, which address receives notifications. No passwords — keep those in a company password manager. The lack of such a list is the most common cause of the trouble described in our article on what to do when your developer disappears.
Release process
How to bump the version number, how to build a release version, where the Android upload key is and whether the app uses Play App Signing, how to sign the iOS build, which testing track to release to first, what to check before publishing. If releases are automated, the document can be short, but it should still say what to do when the automation fails. We describe a pre-release checklist in our article on testing an old app, and automation in our article on CI/CD and fastlane.
Deadline register
SSL certificates, the APNs certificate, the Sign in with Apple secret, domains, provider contracts, library deprecation dates and the stores’ yearly requirements. Each of them will expire at some point, and it’s better for them to be in a calendar than in one person’s memory. What most often expires on the server side is covered in our article on an unmaintained app backend.
Technical decisions
Short notes on why something was done a certain way. The format is sometimes called an ADR (Architecture Decision Record): context, decision, consequences, date. The most valuable notes are about workarounds, e.g. “we don’t update library X beyond version 4, because it breaks sign-in on older Android versions — issue reported to the provider under number…”. Without such a note, the next developer updates the library and discovers the problem in production.
Key flows and integrations
Sign-in, payments, push notifications and data sync described at the level of the flow: who sends which request, where the confirmation arrives, what happens on an error, which webhooks exist. These are the places where an outage costs the most, and the code is spread across the app, the backend and the external service.
API description
Ideally generated automatically from the backend code in OpenAPI format, so it doesn’t drift from reality. Plus the rules for versioning and backward compatibility, including how the minimum supported app version works.
Known issues and technical debt
A list of things the team knows are wrong, with an assessment of urgency. Such a list isn’t an admission of failure, it’s a plan. How to prioritise it is covered in our article on technical debt.
Where to keep the documentation
In the repository, next to the code, in plain Markdown files — for example in a README.md file and a docs/ folder. This has three advantages:
- the documentation changes with the code, in the same changes and reviews,
- it moves to the new team together with the repository, with no separate handover,
- it doesn’t depend on the vendor’s tools — a wiki on an agency’s private account disappears when the contract ends.
The exception is passwords and keys: those go in a company password manager that more than one person on your side can access.
How to keep it up to date
- Documentation is part of the change. If a change touches building, releasing or an integration, it isn’t done until the relevant document is updated.
- The new-person test. Every so often, someone outside the project tries to build the app using only the setup guide. Every point where they have to ask is a bug in the documentation.
- A quarterly review — alongside the review of dependencies and the deadline register.
What to put in the contract
- Documentation as part of the acceptance of work, not an add-on at the end of the project.
- Handover of the documentation when the cooperation ends, together with the code and access.
- Rights to the documentation alongside the rights to the code — when copyright is transferred, it’s worth making sure the transfer covers the documentation too.
More on what to agree with your vendor in our article on the mobile app maintenance contract.
What it costs
Writing up the minimum for an existing medium-sized app usually takes 16–40 hours from someone who knows the project, or somewhat more if a new team does it during a takeover. Keeping the documentation current is a small part of each change. For comparison: missing documentation when switching vendors usually costs the new team anywhere from a few days to a few weeks of reconstructing knowledge — paid for out of your budget.
Five checkpoint questions
If you want to quickly check the state of your app’s documentation, ask yourself and your vendor these questions:
- Could someone outside the project build the app using only the setup guide?
- Do you know where all the accounts are and who owns them?
- Is the release process written down, and do you know where the signing keys are?
- Do you know what expires, and when, over the next year?
- Is there a list of known issues?
Every “no” is a place where your app depends on one person’s memory.
Summary
Technical documentation for a mobile app doesn’t have to be extensive to be effective. A few short documents kept in the repository — a setup guide, a system map, registers of accounts and deadlines, the release process, decisions and known issues — mean that a change of vendor takes days rather than months, and an outage doesn’t have to wait for one person to come back from holiday.
During a mobile app takeover we fill in the gaps in the documentation and leave it in your repository, and as part of app maintenance we update it with every change. If you want to know what’s missing in your project, order a free app analysis — you get the results in writing.