How to Build Onboarding Documentation for Software & IT Teams

Congratulations: you just hired a new employee who’s the perfect fit for your team! Now, how do you make sure that you’re equipping them for success during the onboarding process?

Part of ensuring successful onboarding for your new hire is to have documentation of your team’s onboarding process — a kind of checklist to confirm that your new hire is ready with all the equipment and logins they’ll need on their first day. You’ll also want to have a checklist that details all the key information they’ll need to learn in their first few weeks.

In this blog, however, we’re going to focus on a different type of onboarding documentation — the kind your new hire will need in order to actually perform their new role. This is the technical documentation that they can use as a resource both during the onboarding process and beyond.

How to Build Great Technical Onboarding Documentation

Great technical onboarding documentation should be comprehensive, but not dense. It should be easy to access and understand, and it shouldn’t be meant for a one-time use; it should be a resource that your new hire (and the rest of your team) can use all the time to share information and stay up to date.

Here are three ways to build great technical onboarding documentation that has lasting value beyond those first few weeks. 

Document the Essentials

One of the most common challenges when it comes to building documentation is a lack of time, both to create documentation and to keep it updated. To ease the load on your team, only create the documentation that’s essential to get your new hire up to speed. They’ll be able to learn a lot on the job — but there are a few important pieces of context that will provide a necessary foundation. 

Onboarding Essentials for Software Teams

C4 Model

A C4 model is one of the best ways to introduce your new team member to the structure of your software architecture at multiple levels of detail. This set of diagrams can be used to model microservices, visualize cloud strategy, and more.

C4 modes are simpler than UML diagrams and can describe multiple systems rather than being locked into one type, like an AWS, GCP, or Azure diagram would be. If you’re pressed for time when building onboarding documentation for your new software engineer, this is a great place to start.

Additional Architecture Diagrams

Although the C4 model is a great starting point for introducing your new hire to your system’s structure, a full understanding of its architecture may require more specific diagrams, like AWS diagrams, GCP architecture diagrams, or Azure architecture diagrams.

If you’re able to go deeper than a C4 model or have complex structures that may differ from what your new hire has worked with before, creating additional architecture diagrams will be a great help to them.

UML diagrams that describe system structures and activities may also be vital to getting your new hire up to speed before they start working on new projects. Our resource on the essential application architecture diagrams provides a good list of which diagrams are most helpful for different purposes.

Onboarding Essentials for IT Teams

Process Flowcharts

One of the primary goals for IT teams is to deliver fast, consistent service to every customer, and one way to make this happen is to have clear, defined processes that every member of the team follows to respond to tickets and troubleshoot issues.

Having documentation of your team’s ITSM processes, especially in an easy-to-understand format like a process flowchart, will help new team members get up to speed fast and provide service that’s as high in quality as those who have been part of the team for a while.

Network Topology Diagram

Knowing the physical and logical structure of your organization’s systems is one of the most important things to know when troubleshooting and providing IT services. Having a helpful visual layout of these structures in the form of a network topology diagram can be a great resource for your new hire and a helpful reference for the rest of your team as well. 

Create Clear Structure

Your new hire should be able to find what they need when they need it without having to spend significant time each day searching for information.

If you’re creating your onboarding documentation in Confluence — as many software and IT teams who work in Jira do — you can use labels to organize the most important content that your new hire will need to reference as they learn the niche technical information on which they’ll need to quickly become an expert.

What can be found on each page should also be clear at a glance. Using subheadings and adding a table of contents to each page helps your new hire know what to expect whenever they open a new page, lets them jump to the section they need, and allows them to find information quickly without wasting valuable time finding the right page.

Develop Engaging Pages

Give your new hires the information they need without making them read a novel. Whenever you have the opportunity to present key information in a visual format, such as through architecture diagrams and process flowcharts, make sure to take it.

Along with relevant visuals, always use headings and subheadings to break up long chunks of text, and use active, simple language whenever possible.

Our blogs on how to create engaging Confluence pages and how to supercharge your Confluence documentation have all the tips and tricks you’ll need to create effective documentation that will be a benefit to your team’s productivity, not a drawback. 

Get Your New Hires Up to Speed in No Time!

Ready to start putting together all the information your new hire will need to start contributing fast? Don’t forget to start your 30-day free trial of Gliffy’s Confluence app to add in visuals — they’ll help you save time by requiring you to write less, and they’ll take less time for your new hires to read, too. 

TRY GLIFFY