Onboarding driven documentation

When starting a new software engineering job, it’s an exciting moment getting let loose on the code for the first time. I’ve been in the same job for about 3 years now but still remember the satisfaction of raising my first pull request there.

However, whether or not a new starter is able to ship code in the first week on the job is dependant on several factors. Arguably the most important factor being good documentation.

Documentation is very often stale at best and completely absent at worst. The limitations of your systems’ documentation will become most apparent when you’re trying to help someone new understand them. Having fresh eyes on a system and its documentation is an opportunity not to be missed. The best person to judge how well a system is documented is someone who has absolutely no idea how the system works. Having a new starter is a great opportunity to improve your documentation.

Every time a new engineer joins, their first task should be to work through the docs of how to setup local version of the services they’ll be working on. Also, how to deploy them, view the logs, monitor them, access its data etc etc. If they get stuck or something isn’t working, that means the documentation isn’t good enough. With some assistance they can amend or add to the documentation themselves. This is a win all round: the docs get updated, the new engineer makes meaningful contribution from day one and it instills an idea of keeping on top of documentation being an important part of the process in your engineering culture.