One of the best-documented woes in the world of software development is the lack of good documentation and the drudgery involved in producing it. And just as well-documented is the recognition and acknowledgment of its importance.
Producing onboarding documentation (and internal documentation in general) doesn’t have to be so painful. And the investment is more worthwhile than you might have ever realized.
Good onboarding documentation is actually an investment in success for growing dev teams. And this means success on many levels:
- The success of the individual developers being onboarded – making them confident, productive, and able to contribute more quickly.
- The success of the team – making the recruiting and hiring process easier, expanding the potential pool of talent, and minimizing the need to continually expend team resources in providing the same training and mentorship over and over.
- The success of the company – improving the quality of the codebase and reducing the negative impact of legacy code and technical debt.
Strong onboarding documentation has never been more important than it is now
Opportunities for success are everywhere, investment money is flowing, acquisitions of startups are happening with unprecedented frequency, and companies are going public with IPOs at stunning valuations. The challenge is finding the talent to fuel this growth.
Onboarding needs to happen remotely
The “new normal” of working remotely is a part of team landscapes globally. Teams work remotely, interview candidates remotely, and share knowledge remotely.
Remotely is the operative word here.
Add in consistently evolving and more complex codebases, learning a broader pick of devtools, more varied and sophisticated tech stacks, faster deployment cycles, end-to-end testing, finely tailored use cases, and complex team processes – remote onboarding is that much more challenging.
Onboarding documentation solutions
There are unprecedented opportunities. While good onboarding documentation is not the answer to everything, it can be a big part of the solution to the challenges we’re facing.
Good onboarding documentation widens the talent pool
Bringing on new developers is an investment.
Consider the situation in which you need to replace a developer who has recently left your team… or the more ideal scenario where you have the budget to expand your headcount. While no one expects a new developer to onboard in minutes and start producing code in hours, your goal is to hire a highly competent developer who can hit the ground running.
Good documentation makes it possible, practical, and cost-efficient to bring on junior or geographically dispersed devs without investing in huge hours of face-to-face onboarding. It also ensures sufficient coverage of the codebase, provides consistent, high-quality training, and promotes increased confidence – with the investment of team resources in bringing new devs up to speed significantly reduced.
What type of documentation makes it happen?
Comprehensive documentation consists of knowledge collection and transfer at three different levels:
Inline documentation: Tactical documentation in the form of code comments that explain a specific line or area of the code in an isolated form. They are essentially quick notes to future devs or to your future self.
High-level documentation: The big picture. This might include a layout of the code architecture, the business logic behind it, and reasoning for major decisions. It might describe the interactions between various repositories and the role of each repository, or main modules within a specific repository. It may also include a structure diagram of the system.
Walkthrough Documentation: All the information that provides developers with what they need to do their jobs effectively including:
- a guided tour of the codebase – for example, interactions between different modules and the actual lines of code that make the calls between them
- a step-by-step demonstration of how and when code should be used. For example, how to use internal APIs
- a tour of how data flows through the various components of the system
- explanations of complex algorithms – their actual implementation
- detailed README files with an overview of what lives in a certain directory or branch of the code and dependencies
- … and more!
As you can see, the Walkthrough Documentation is where the real action is. Unfortunately, this is precisely the type of documentation that’s most often lacking, and it’s not difficult to understand why. Producing this scale of documentation doesn’t have to be overwhelming.
Read on!
What makes documentation effective?
All documentation is most effective when it is found exactly when and where it’s needed. When a developer is working on a specific section of code, some sort of contextual alert should appear, letting them know that relevant documentation exists. This could take the form of a Swimm IDE plugin notification or a comment with a link to the relevant location.
Of course, for documentation to be useful, it should also be easily accessible and easy to find. All the information should be available, indexed, and searchable in a centralized location.
Specifically, in the context of onboarding new developers, it’s particularly helpful if there’s a flow for them to follow so you can be sure they’re getting all the information they need in the most logical and effective order. You could do this by creating an onboarding training “syllabus.” Or you could work with a Swimm Playlist to collect all the materials in one place (documents, links, videos, Markdown files, images, etc.) and walk your new team member step-by-step through the onboarding process.
Why onboarding documentation is worth it
There’s no doubt that creating this depth and quality of onboarding documentation is an investment. But consider that the major expenditure of resources and effort happens only once. Then you reap the benefits every time you bring on a new developer. You are essentially cloning a mentor, making sure they are always delivering the required information, and doing it precisely in the most efficient way.
It has the potential to work beautifully… but only if the documentation is kept up to date. True, this is an investment that’s ongoing, but a much smaller one if it can be done consistently and efficiently. That’s where code-coupled, automatically updated, Continuous Documentation comes in.
Benefits beyond onboarding
Investing in high-quality internal documentation has benefits far beyond onboarding:
- You never have to be concerned that valuable knowledge will walk out the door just because a developer does.
- Developer productivity is maximized by them having the documentation they need, exactly where and when they need it.
- A better understanding of how the codebase fits together avoids the proliferation of dreaded spaghetti code.
- Even when your codebase contains lots of legacy code, you can compensate for some of this technical debt by minimizing the documentation debt. It might be legacy code, but at least it’s understood… and easier to refactor when the time comes.
- You reduce the chances of mistakes – and even potential disasters – by ensuring that all devs follow safe deployment procedures.
- By revealing gaps in standardized procedures, the documentation process pushes you in the right direction towards putting them in place.
How to create documentation
A few get started options for creating documentation:
- Consider a Docuthon. Similar to a hackathon, Docuthons help dev teams cram a lot of documentation in bursts.
- Task new developers with improving the documentation while they are onboarding themselves. No one knows better than they do what they need to know and where the documentation could have helped them more. Also, asking them to contribute to the documentation provides the added benefit of a morale boost and makes them feel like a contributing member of the team right from the start.
- Use tools that make it easy. Swimm’s code-coupled editor, Auto-sync, IDE integrations, and Playlists make documentation efficient, easy to use, and easy to maintain.
We invite you to sign up for a free demo and experience the benefits of Continuous Documentation for yourself.
Bottom line
While creating comprehensive onboarding documentation and keeping it up to date may seem like another thing to add to your to-do list, it’s an investment in dev team success that pays dividends time and time again.
Learn more about onboarding documentation with Swimm.
