My Software Self-Onboarding Procedure

Hello reader, have you ever thought about how you would get up to speed with software development when in an unfamiliar codebase? Whether you are working in a new codebase within the same company or starting at a new company you’ll need to go through an onboarding procedure before you are able to contribute changes to the code.

Due to some recent events I’ve been pondering this question and I realised that while it’s nice to have a well documented onboarding procedure to follow a lot of onboarding procedures are out of date or incomplete. Furthermore the more experience you have as a software engineer the faster you’ll be expected to onboard.

Therefore, I think it’s useful to think through how you would onboard yourself when faced with an unfamiliar codebase. For my procedure that I’m going to lay out below, I’m going to assume a worst case of being dropped into the new codebase with minimal or no onboarding. This way, no matter what circumstances I encounter, I should be able to quickly get up to speed without too much downtime.

Something that I will be doing is writing things down as I go through the onboarding process. This will make it easier for me to update the documentation later. If updating documentation makes sense as I go then I will do so, but some documentation is easier to write once you have a more complete end to end understanding of the system.

Getting to Know Production

My goal here is to be able to use the application in the same way that the customer would as well getting familiar with the logging and monitoring of the application. I’ll also become familiar with the lingo of the application which help me not be so lost when I’m looking through issues, attending meetings or talking with my colleagues about work.

The follow is a short checklist of some of the things I’ll be doing as part of getting to know the production deployment of the application:

• Figure out how to access the production deployments of the application
  • What are the endpoints or URLs?
  • Are credentials required to use the application? How do I get such credentials if so?
    • Are there QA, test or developer credentials I can use?
  • Do I need special access to production systems?
• Get a general sense for how the application is deployed
  • Running on AWS? Kubernetes? Azure? Serverless?
  • How the application is scaled across users? Sharded? Load balanced?
• Review the logs and monitoring
  • Can I see my usage of the application reflected in the logs?
  • Does the application report statistics to influx or similar?
  • What nags are configured to fire?
    • Where are the nags raised? Email? Team Chat?

Running Locally

After getting to know the application the next step would be to get the application running locally on my machine. This will allow me to play around in the code to gain a deeper understanding of what the application is doing.

• What software do I need to be able to work in the codebase?
• What prerequisites do I need to setup before I can run the application locally?
  • Especially important if the application needs to connect to a database. Which database do I use for local development?
• Where is the code hosted? What credentials do I need to set up before I’ll be able clone a copy of the code to my local machine?
• What extra steps do I need to follow in order to compile and run the application from a fresh copy of the code?
• While the application is running, where are the logs saved? Can I view the logs resulting from my actions like in production?

Getting changes to production

Now that I’ve gotten the application running locally the next step is become familiar with the how to get changes to production. This is also known as the software development lifecycle.

• Figure out the location of the project for the application within the task management system.
• What lifecycle stages does work progress through?
  • Triage, Assignment, Development, QA, Merge, Release, Verify?
  • Triage, Assignment, Development, Test, Merge, Release QA, Release, Verify?
• What is the task triage process?
  • Is it different for bugs vs features?
• Working on a task
  • What’s the branching strategy?
  • What’s the code review process?
  • What’s the merging strategy?
  • What’s the testing strategy?
• What build server is used?
• Is there a lower staging environment to deploy to for system wide testing?
  • Can I deploy a branch for testing?
• Who is responsible for the QA of the application?
• Who is responsible for releasing the application?
• When are releases performed?
• Who verifies changes in production?

Documentation

At this point I should be all onboarded and ready to contribute to the codebase. However I have just spent a bunch of time learning how to get started in this codebase and thus there is no better time than now to ensure that the documentation accurately reflects the steps I had to go through to get to this stage. So while I could jump straight into picking up work, I’ll first spend some time ensuring that the documentation is accurate and up to date.

• What is used as the company documentation? Cloud documents? Wiki?
• Ensure that any documentation is accurate and up to date.
• Ensure that related documentation is located together.
• Ensure that the documentation can be found via searching.
• Remember to review readmes within the application codebase as well.

Final Thoughts

Having thought through this onboarding procedure and having written it down, I feel prepared to work on any code base in future. It’s just one less thing for me to worry about when I’m in unfamiliar territory. If you are the type to get nervous when starting at a new company or within a new codebase then going through this exercise yourself should help ease your worries. If you are already working within a codebase and you need something to do in your downtime then going through this exercise will ensure that the documentation around your application is up to date, greatly helping anyone new joining your team.