Developer Onboarding Documentation Must-Haves

In 2017 the story of a young developer who accidentally destroyed a production database became viral. In less than 24 hours it had received 28k upvotes and 4,2k comments on Reddit - a stunning display of support and sympathy from the tech industry.

What jumps out to me, however, is how badly the onboarding process failed this young engineer: the reason why they crashed the entire production database is because they followed misleading instructions in an onboarding document on how to set up their local dev environment.

Although this is an extreme example, the onboarding process has a significant impact on new hire retention and productivity: many companies lose up to 25% of their employees in the first year and the ones that stay, have a long ramp-up period (~8 to 12 months) before they are fully productive.

A well-planned onboarding process can raise the retention of new hires by 82%, while increasing their productivity by 50% or more.

Must-Have Technical Onboarding Documentation

---

Whether you have a highly structured onboarding process or a self-study approach, your newly hired engineer will need the following bare minimum set of documents to ramp up as autonomously as possible and minimize the amount of impact on the rest of the engineering team.

As a note, the onboarding process is much more than just mastering technical proficiency, it also encompasses learning how to communicate and collaborate with your new team. Check this blog post for a complete walk through of onboarding best practices.

ENVIRONMENT SETUP GUIDE

Software engineers can’t start building without a properly configured local development environment, including installing the necessary software, configuring IDEs, setting up version control, and connecting to relevant databases or services.

Without step-by-step instructions (ideally standardized for the entire team), new engineers can waste days trying to set up that local dev environment correctly… and in the very worst case scenario described at the start, with incorrect setup instructions, they can blow up the entire production database!

SYSTEM ARCHITECTURE DOCUMENTATION

A system architecture overview is a crucial tool for communicating the high-level design and rationale of a software system. Many teams make the mistake of subscribing to the belief that the "the code documents the system”. However, that leaves them with only half a story: for all stakeholders, developers, and maintainers to understand the structure, behavior, and quality attributes of the system, you need to know the history behind architectural decisions and how different parts of the system relate to each other.

Diagramming is also a key part of a system architecture document: it provides a way to understand and explain complex systems and processes at a glance, facilitating collaboration (especially with non-technical stakeholders).

There are many different types of software architecture documents that your team can produce. Likewise, there are many different types of diagrams you’d need to select and manually create to capture the full scope of a system architecture.

A time- and effort-saving approach is to use a diagramming tool that supports these key features:

• Elegantly and accurately displays the different layers of a distributed systems (e.g. client, load balancer, API, web server, application server, caching, CDN, database, etc.), the relationships between components and their dependencies
• Stays automatically in sync with your code, eliminating the need (and stress) of version control.
• Provides a shared, web-based workspace for distributed teams to collaborate in real-time or async.

Having all this information in a single, easy-to-navigate, always up-to-date location ensures a quicker time-to-productivity for new engineers.

(Pst - Multiplayer can do all that and more! Sign up for free 😉)

TECH STACK DOCUMENTATION

List all the technologies, programming languages, frameworks, libraries, and databases used by the team.

CODEBASE DOCUMENTATION

This document should describe:

• The overall structure of the codebase (including directories, modules, and key files).
• The naming conventions used for files, directories, classes, and variables.
• The database schema (including tables, relationships, and key fields).
• The data models used in the application, along with their attributes and relationships.

API DOCUMENTATION

Similar to the system architecture documentation, an easy way to document all aspects of your API layer is to use a dev tool that:

• Provides comprehensive (and automatic) documentation for endpoints, request/response formats, and authentication mechanisms.
• Includes examples of API usage and common use cases.

TECHNICAL PROCESSES DOCUMENTATION

While more senior engineers may know how to jump straight from a simple, written task into the building of core business logic, that might not be true for more junior engineers or those not familiar with the team’s domain yet. Ultimately, helping new engineers gain familiarity with both business logic and development best practices, allows for a quicker ramp up.

The technical processes documentation aims to introduce the software development methodology and outline the following processes:

• Deployment process, including scripts or tools used to deploy the application to various environments (e.g., dev, staging, production).
• Code review process, including branching strategy and coding standards
• Issue-handling strategy, including tips and strategies for debugging common issues and errors. Bonus points if it also provides examples of log messages or error codes and their meanings.
• Testing strategy (e.g. unit tests, integration tests, and end-to-end tests)
• Security best practices, including authentication and authorization mechanisms.

Common Mistakes to Avoid

---

A negative onboarding experience can make new hires twice as likely to look for other jobs in their first year. Not to mention that a poor onboarding process lengthens the already long ramp up period, delaying when a new engineer will reach their optimal productivity.

Ultimately, companies that invest in the onboarding process and avoid the following mistakes ensure higher overall effectiveness, quicker product development, and a lower risk of turnover.

(1) Don’t underestimate the impact of the onboarding documentation.

Documentation is a powerful tool that sets the tone for the overall success of the onboarding. Lack of good documentation not only slows down the entire onboarding process and adds overhead to the team, it’s also a red flag indicative of deeper problems within the engineering culture and work.

(2) Don’t reinvent the wheel - leverage the right tools.

The documentation has to be accurate, updated, and colocated in a single place. It’s almost more harmful to have documentation that is incomplete, contradictory, and scattered throughout an unknown number of different systems, than having no documentation all.

However, this doesn’t have to be a manual, burdensome, and time-consuming task for the development team - choose the right tools that automatically and collaboratively support your documentation needs.

(3) Onboarding documentation is not just useful for onboarding

The value of the documentation you’re preparing extends far beyond the initial onboarding process. Consider it as an ever-evolving playbook of your team's operations. A well-maintained and up-to-date documentation repository becomes a shared knowledge base, helping all team members, regardless of their tenure, stay aligned and informed.

• You don’t have to be concerned that valuable knowledge will walk out the door just because a developer does.
• Team productivity is maximized by them having the documentation they need, exactly where and when they need it. In the midst of complex projects or when troubleshooting issues, having a centralized source of information eliminates confusion and accelerates collaboration.
• 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, it’s well understood and it’ll be easier to refactor when/if the time comes.
• Regularly updating documentation encourages the team to reflect on processes, identify inefficiencies, and drive continuous improvement. It becomes a tool for refining workflows and evolving with the ever-changing tech landscape.

By recognizing the lasting impact of onboarding documentation, companies can invest wisely in their efforts (especially in his period of "doing more with less"), nurturing a thriving engineering culture built on the solid foundation of knowledge and collaboration.

---

Multiplayer allows you to visualize, design, and develop your distributed software with a visual and collaborative tool. All the information you need to onboard a new developer — system architecture overview, codebase documentation, API documentation — is at your fingertips in an easy-to-navigate, always up-to-date platform. Sign up for free to see for yourself! 😉