I find that authoring documentation is best done at the end of a project. Writing it too early means it needs to be re-written as things change.
Unfortunately, life happens. On many projects, almost no time is available for documentation at the project’s end. This may seem irresponsible, but it’s the tradeoff teams and clients choose to make.
If you find yourself in this situation, make the most of your time by strategically prioritizing the documentation you write.
1. The Bare Minimum
No matter what, take the time to at least document:
- Links to the primary documentation repository (e.g., Dropbox, Google Drive, Confluence)
- Links to all code repositories
- Where to find credentials (e.g., 1Password, the client’s password manager, a sticky note with handwritten credentials)
- Names and contact info for people most recently associated with the project
- What do to next if the app is in production and on fire
You should be able to get the first four items done in an hour. The last is a bit more open ended, so I’d recommend timeboxing another hour for the task. That should mean covering this whole list would take no more than two hours.
2. A Visualization of All Major Components & Data Flow Between Them
After the bare minimum, the single most impactful document you can create is a visualization showing the major components of the system and how data flows between them.
Major components can include things like:
- Server processes
- Databases
- Caches
- Mobile clients
- Desktop clients
- Embedded clients
- Physical hardware devices
- External services
The visualization does not need to be very detailed about what data is flowing. Instead, the goal is to show how everything is connected.
This visualization is not as detailed as the one above, but it took less time and effort to create and is still immensely valuable:
If time and attention to build the visualization are limited, a hand sketch on a piece of paper or whiteboard is perfectly fine. The goal is to paint the picture of the ecosystem for a reader, not create a pixel-perfect image.
3. Additional Helpful Documents
Time permitting, consider including some of the following:
- Prerequisites to run the software
- Quick start to get the app running
- Error debugging
- How to run the tests
- How to deploy a hot fix
- How to deploy a long-term solution
- Links to continuous integration and other services
- What physical environment does the software run in?
- What are the major components of the ecosystem?
- FAQs
- What assumptions and shortcuts does the next project team need to know about?
- What non-standard software patches are applied and for what reason? When can they be updated or removed?
Pull from this list as it makes sense for your project.
Everyone wants more documentation, but nobody wants to write it. I hope the above tips are helpful in balancing these two competing demands.