Article summary
- A List of All Services Billed for the Project
- Access to All Those Services
- Documentation on Updating Things Like Site Certificates
- Documentation on How Often and When Certain Scripts Need to be Run if Applicable
- Documentation on Accessing the Production Database and Logs
- Documentation on Environment Setup
- Documentation on How to Get Someone Access to the Server Through SSH if Applicable
Before handing off a maintenance project (or really any project), here are items you should document or get from the client or the previous person who worked on it. Incidentally, these are things you should get from the client or the previous person who worked on it if you are the new person maintaining the project.
A List of All Services Billed for the Project
This should include information about which ones are recurring and which ones someone needs to do every year. Sometimes issues come up in a project that inevitably lead to something that requires billing, like a site cert, perhaps, or emails.
It’s good to know all the services that incur billing and when they get billed, particularly if they’re not recurring. And, if it is recurring, you should document when the payment option expires so the next person can prepare for that to get updated.
Access to All Those Services
It should go without saying that if a software maintainer can’t access the services used, it might be hard to address issues that come up. More generally, it’s going to take longer and involve waiting until they get access.
It’s also a good idea to get rid of services no longer used and remove those accounts. It’s a huge pain to figure out which services are actually important if many are no longer needed.
Documentation on Updating Things Like Site Certificates
Knowing what cert site the project uses should be covered above. But, it’s also really good to know the steps someone would use to update that cert. Don’t make the assumption that everyone has experience doing this.
Documentation on How Often and When Certain Scripts Need to be Run if Applicable
Hopefully, a project with scripts that need to be run periodically is set up so you don’t need to do them manually. This isn’t always the case, but it’s less of an issue on a job if it’s only once a month. You should know and document what those scripts are, how to kick them off, and when to do them. This goes for those scripts run on a job, too. Someone might touch them eventually for whatever reason, so document them.
Documentation on Accessing the Production Database and Logs
A lot of projects use databases. This will mean needing not only a local copy but also documentation on access to the production database. It might not be often this will need to be looked at, but issues that crop up are hard to address on a local copy, especially if the local copy is fairly out of date. Along with that, it’s much more likely the new person will need to look at the site logs. Knowing how to view those is very important.
Documentation on Environment Setup
Some projects might be fairly easy to set up locally, but it’s a good idea to keep these environment-related details documented. If someone has to be on multiple projects with conflicting versions of, say, Java or Python, it’s a pain. So, do what you can to try and make their life easier. But also just document all the things they might need for their environment and if there are any small “gotchas.”
Documentation on How to Get Someone Access to the Server Through SSH if Applicable
If the project utilizes some server, then, inevitably, the new person will need access to the production server. This might be for logs, maybe running scripts, or updating site certs. It’s good to know how to access the server or give someone access if through SSH.
This is likely not a complete list, and I’m not going into detail about how to document these things. Just document all the things, and when the project gets handed off, make sure the new person is given these documents directly. Yes, please document in the repo and sanitize as necessary, but still give someone a copy directly, especially if there are items that can’t be in the repo because of sanitizing.
Basically, if there are important things in the project that someone new will need to know eventually, then document it. I can almost guarantee if you don’t document something from this list, if applicable to your project, then it will inevitably be an issue for whoever is maintaining the project. So please, document all the things.