Creating tutorials for your codebase is not an intuitive task for many teams. How to tackle it? What makes for a good tutorial? How do we measure the effectiveness of a code tutorial correctly?
We covered dozens of tutorials and approaches at different companies and organisations, and here are the 5 elements we found every code tutorial has to have. We’re willing to go as far off and say: if your onboarding tutorials do not meet the following criteria – you probably shouldn’t bother creating them in the first place.
What makes a code tutorial effective?
While providing your engineers with code tutorials can be a time consuming task for everyone, tutorials pose some innate benefits that will help keep your onboarding programs effective and sustainable and internal knowledge sharing levelled up.
Great code tutorials are:
- Focused – highlighting just the part of the repo which your engineer needs to learn to get started. If the readers need to look through dozens of paragraphs to find what they were looking for, they might not even bother searching. In other words, tutorials are not like your history essay from high-school – You lose points for length and breadth.
- Highlight the “Why”. They show a clear explanation of the logic behind the code and/or why it is like it is now.
- They show a process rather than the mere solution. It’s much easier to understand code by seeing the process of its creation or the flow of information, rather than just looking at a freeze frame of what it looks like now.
- Tinkering – they enable a sandbox experience or learning by doing. It’s similar to getting thrown a task from the backlog in the sense that it is hands on, however it is structured, and guided in a way that evokes deductively understanding codebase logic, and also does not require the time and investment a backlog task would.
- Up to date. They have to be practical and up to date with the current code. What usually kills good tutorials is if they are outdated. Not only will they waste the reader’s time, they might cause actual damage by misleading. This is the number one reason that many engineers distrust tutorials, and documentation in general.
Recap
Good tutorials are hard to make and maintain. Although, easier said than done, the key is to keep them updated, focused and encourage an independent learning process. The next step to tune-it up, would be to make sure we measure the effectiveness of our tutorials (more on that in a future post), and gather feedback to improve over time.
