Getting someone new on a team is always exciting. Developer teams have shifted to Slack and Zoom and it has been quite challenging.
We’ve seen collaboration slow down 3x during WFH. Yet, a solid README could increase developers' productivity by 1.7x. This could lead to informed questions by new teammates on Slack and Zoom and better pull requests.
What’s onboarding? It’s the ultimate knowledge transfer. getting someone new from knowing nothing to pushing code in production.
The goal of this post is to establish a template for the ultimate README.
Sections of the README should be easy and helpful for both readers (new developers) and writers (more experienced developers):
Onboarding onto large code is not about understanding a lot of code. It’s about understanding the structure, concepts and abstractions of the system.
There are basically 2 approaches to onboarding:
Onboarding is about mapping what your new dev doesn't know (unknown unknowns).
When onboarding, you need both.
A good README is about giving a top down approach and pointing your new developers to the starting point of the bottom up approach (specific code locations).
Your new developer is successful when he pushes his first code to production. The goal of a good onboarding guide is to help him to be effective in that process.
So how do we pave the path for your new developers success?
So how do we set up your new developers for success?
A good README explains what’s already in place: the existing code, the processes and the team with the goal that your new developers can evolve it. Here are some of the high characteristics of a good README:
So here goes the template. It should be quick to write from scratch if you know your repo.
One of the problems with nodetube’s README is that it is aimed towards users and not contributors.
Known unknowns about nodetube:
Unknowns unknowns: we hope to clarify by applying our README template