Here's a list of things I find useful to check off when writing handover documentation for source code.
These get checked at the end, but they're at the front of the document because they're good to keep in mind the whole time
- Do these instructions work cross-platform? If not, which platform do they work on?
- If the source of truth is not this document, should some of the questions be answered with links (to eg confluence/other repos)
- Does the readme repeat information? (repeating information means it's likely to be longer and less likely to be changed correctly)
- If the information that is documented changes, will the maintainer know to update the readme?
- Should the source code include comments to remind the programmer to update the readme?
- Should the PR template include a reminder to update the readme?
- Is there anything in the project readme that should be moved somewhere else?
- What are the prerequisite build tools I need to have installed? (npm, JVM, etc). What versions?
- How do I build the source?
- What is the versioning strategy?
- How do I run the tests?
- If I can stand it up locally, how do I do that?
- When this is deployed, how does it fit into the rest of the ecosystem?
- If I can run it locally, what is different about the deployment infrastructure?
- What components are deployed from this repository?
- What components from other repositories are required? (include links to the other repositories)
- How is the software configured? (often there's more than one config source, eg env vars set during deployment, a secret store, config files during build etc).
- How can those configurations be changed?
- What kind of tests are there? (integration/unit/contract, etc).
- What is intentionally covered by the tests?
- What is intentionally not covered by the tests?
- What is the structure of the modules in the source?
- What is the intention behind the code layout? (which concerns have been separated by this design)
- Is there any documentation other than the source code? (examples might include a link to something like a list of ADRs, architecture review meetings, flow diagrams, etc)
- Where is the project issue tracker? (ideally a link to all the issues associated with this repository)
- What are the deployment environments?
- How do I deploy / release?
- How are the versions tracked?
- How do I know what is currently deployed to each environment?
- How do I tell whether it is working / not working?
- What do I do if it isn't working?
These things are useful if you're not handing over the whole project to a new team, and are instead using the documentation for bringing in new team members. Usually these are links to ways-of-working documents in a wiki or team space somewhere.
- What does the team development cycle look like? PRs, code reviews and walkthroughs?
- Which team owns this code?
- Is there an on-call list for this project?
- How can I contact them?
nice docs :)