We had the joyous occasion of having a new developer join VIBBIO this week 🎉🔥 Some people choose to see this as something that “slows the team down” short term as someone needs to point the new developer in the right direction to get the development environment up and running. When viewing this as a distraction and a loss of productivity you are missing out on a great learning opportunity of seeing your codebase from a different perspective than what you normally have. If you treat it as an opportunity for learning you will learn more about your own code and you will help those reading the documentation for the first time. Wins all around 💯💪🏼
One year, one goal
The past year we have been working on making our platform more robust and less complex (there might be a separate blog post about this later) in terms of infrastructure. In short we have transformed a micro service architecture into a monolithic one. A side effect of doing this was that we simplified the developer experience quite a bit (not saying this will always be the case whenever you do this, only that it was in this case). Having a new person join our team was the perfect opportunity to see if we were heading in the right direction 🔮.
Three key points to succeed in creating a good first experience for your developers
In order to make it easy for new developers to join your team there are three things which make all the difference.
- Location - where is the documentation stored?
- Structure - how is the documentation structured?
- Automation - how is the process of setting up required software?
🏡 Location, location, location 🏖
Real estate brokers will tell you “it is all about the location”, the same thing goes for documentation. If all your documentation reside in some wiki or are scattered randomly around in a folders structure you have given people coming in a rough start. You have also set yourself up for having a lot of outdated documentation.
Developer documentation should reside next to the code of a module. In many cases these days this would mean a [Readme.md](http://readme.md) file residing in your source control repository of choice. When doing this you will have:
- Increased the chances of the documentation being updated if some major part of the module changes.
- Increased the likelihood of someone finding the documentation.
There are cases when you should / need to split up the documentation into more pieces. Let’s say it is a module which requires some software to already be installed or similar, then you can create a /docsfolder and put the documentation in there. It is essential to make sure this documentation is also linked up from the Readme.md, otherwise it will be an orphaned document that is not read nor updated by anyone.
“A good bone structure will get you far” said my dad 🦴
The developer documentation should have a structure which is common across modules (at least it should be similar for somewhat similar modules). This makes it easier for old and new developers to find the content they are looking for and makes for a predictable experience.
This also comes with the great side-benefit of not having to re-invent the wheel every time you add a module. You adopt a habit of creating great documentation with little effort.
Introduction - short description of the intention of the module
Getting started - a step by step instruction on how to get started with contributing to the module. This should include any prerequisites that the module depends on (like a database, message queue, cloud account setup or whatever).
Deployment - how do you get your contributions out, or in short how to get 💩 🚢 into production.
Other stuff - this is whatever other information which might be useful. It could be troubleshooting documentation, additional information about monitoring or similar. This section will vary greatly depending on what type of module it is.
The goal should be that a new developer can read the documentation from top to bottom and is able to ship the module to wherever its destination may be 💪🏼.
Boring stuff gets sent to the boring robots 🤖
The VIBBIO platform consists of modules written in Javascript running on Node JS or in the browser. Therefore a goal for all our modules is that there should never be more than three commands to get thing setup and running.
git clone <some repository>
npm install
npm start
Regardless of complexity of the module, these three commands should be all it takes to have a module installed and get it running (if the module is a daemon type module or if it is a code library it would be only require the first two commands).
⚠️ Note! There could be some prerequisites for some modules, like installation of a database of similar. That is somethings not worth automating and would be required in addition to the steps above.
Automate all the things (that make sense)
When joining a new company and contributing to a new code base it is always a bit intimidating to ship your first contribution. In order to make this experience better, it is important to automate as many aspects of this process as possible.
Our previous developer experience relied heavily on bot commands, which is a kind of automation. But we have taken this a step further and ensured that deployments to all environments other than production are fully automated. Fully automating it means there is no room for human error and it reduces the fear of messing something up.
Currently we have one human step, because we choose to, in order to get code into production. It is a command which promotes the Docker image in staging to production.
If your documentation smells like 💩, then I am sure your some of your code does too
There are people who view writing, reviewing and updating documentation as something which is not important and does not effect the overall health of a computer system. I would strongly disagree with this view point and I would even go as far as to say that if your documentation smells then there is an increased chance of your code and architecture having the same smell.
How are we currently doing with on-boarding❓
When Eva joined us, she was able to have our user facing application up and running without anyone’s help in no time. She had her first production deployment the next day 🔥💪🏼. This is without having the backend setup, as we decided we’d spare her the pains of setting up a Java development environment. All of our Java code will soon be gone 🎉, therefore getting started with the platform development will be similar to the experience of getting started with the user facing application.
There are still some manual steps when it comes to setting up the backend services, like databases etc. However we are down to that being merely installations and not procedures requiring installation, running scripts, etc.
👀A change of perspective gives you improved insights💡
Having gone through our old documentation and removing and updating it was also an eye opener in how far we have come and how close we are to reaching the goals we set for ourselves almost one year ago.
Seeing how we have simplified and automated some things we were complaining about way back when is a good feeling. It also gives the us an improved sense of accomplishment for having gotten so much done behind the scenes while continuing to ship customer value regularly 💪🏼.
Images used in this article are from Unsplash:
https://images.unsplash.com/photo-1534078362425-387ae9668c17?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb, https://images.unsplash.com/photo-1527430253228-e93688616381?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb, https://images.unsplash.com/photo-1510325256756-87de4e930745?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb