A new developer joining a custom tool usually starts the same way: someone forwards a repository link, a few old e-mails and the words "ask if you need anything". The first week then goes on finding out what the system is for, where it runs and which parts nobody dares touch. That time is paid for twice, once in the developer's fee and once in the changes that did not happen meanwhile.
A one-page briefing removes most of that. It does not replace documentation. It is the page you would give a capable colleague on their first morning so that they can start safely. This article describes what belongs on it. It is written for owners and managers of small companies that depend on a custom tool, and for whoever is handing it on.
Start with what the system is for
Open with three or four sentences in plain language: what the tool does, who uses it daily and what would stop in the business if it were down for a day. Add a short list of the main parts, such as the web application, the database, a scheduled job that sends reports and any outside service it talks to.
Do not describe every screen. The developer will find the screens in an hour. What they cannot find in the code is why the tool exists and which of its jobs the business really depends on.
Say where the code lives and how to reach it
Give the facts a developer needs to open the project and run it:
- Code. Where the repository is, which branch is the live one and how a change gets released.
- Environments. Whether a staging copy exists, where the live tool runs and who hosts it.
- Access. A list of what the developer needs: repository, hosting, database, the admin account of the tool, and any outside service such as e-mail sending or payments. For each item, write who grants it.
- Secrets. Never put passwords on the page. Say where they are kept and who can share them.
Arrange access before the first day. A developer who spends day one waiting for accounts forms an early impression of the project that is hard to change. If you are not sure what the list should contain, our article on who owns an internal tool after its author leaves covers the ownership side in more detail.
Hand over the open issues honestly
This is the part most handovers skip, and the part the new developer values most. List the known problems in three short groups:
- Broken or risky now. A report that sometimes shows wrong totals, a job that fails at month end.
- Planned but not done. Requests that were agreed and not built, with a note on how far they got.
- Decided not to fix. Things that look like bugs but are accepted behaviour, with the reason.
The third group saves the most time. Without it, a new developer will reasonably "fix" something the business chose to keep, or raise it again as a new request. If you do not know the reason for a quirk, say so. "Nobody knows why this is so" is a useful line; a confident wrong explanation is not.
Plan the first week around one small change
Reading the whole codebase is a slow way to learn it. A better plan is to pick one small, real change, for example a label, a column in a report or a minor validation rule, and take it all the way from request to release in the first week. It forces the developer through every step: getting access, running the tool, testing, releasing and telling the users.
A simple outline for the week:
- Day one. Read the page, confirm access works, run the tool locally or on staging.
- Days two and three. Sit with one daily user for an hour and watch the real work.
- Days four and five. Make the small change, have it checked by someone else and release it.
At the end, ask the developer what on the page was missing or wrong, and correct it. The page then improves with each handover.
Name two people to ask
Finish with contacts. Two are enough: one technical person, such as the previous developer or the hosting provider, and one from the business who can say whether a behaviour is right. Add how they prefer to be reached and when they are available. If the previous developer is leaving, agree in advance how many hours of questions they will answer after leaving, and write that on the page too.
Common mistakes
- A link to everything. Twenty documents with no order are not a briefing.
- Access promised, not given. The list is only useful if the accounts exist.
- Hiding the ugly parts. Known problems found later cost more trust than known problems stated early.
- No business contact. The developer can read the code but cannot learn from it what the business wants.
- Never updated. A page that was true two years ago is worse than none.
A first step
Take half an hour and write the page now, while the person who knows the system is still available. Even if no new developer is coming, the exercise shows how much of the tool lives only in one person's head, which is the real risk the page is meant to reduce.
Sources
- Practical guidance based on common software maintenance practice, offered as a planning aid. The examples are invented for illustration. No client results or performance figures are claimed in this article.