How to create your team's technical and onboarding documentation
About this article
By Terrence Caldwell, published August 31st, 2015
Successful dev teams need to be able to move fast, without sacrificing code quality. Since you can't just go out and make clones for your developers (yet...), how do you make your team faster?
Try these two tactics: first, speed up the time it takes to onboard new team members. Second, limit the amount of time your team spends searching for answers to technical problems.
Of course, you want to spend your time building awesome products and not writing docs. At the same time, you need good docs to help your team build awesome stuff. Confluence helps solve the paradox by making it easy to create and document your standard technical docs so everyone can access and contribute to them. In short order you'll be a lean, mean documentation machine.
Check out three standard technical docs that your team can create in Confluence:
1. Onboarding documentation
Getting new people current is critical to your dev speed as well as the future success of your team.
The new hire checklist
Start new hires with a guided task list. You can add tasks to any Confluence page from the editor toolbar:
The new hire task list or 90 day plan should provide direction and useful resources. Include instructions on logging into critical systems and applications, links to important internal resources like company policies, and tasks for meeting members of the team.
Create one universal new-hire task list that lives in your team space. Whenever a new person starts have them copy that page and move it into their personal space. They can edit the task list to add additional tasks, as well as assign themselves due dates for tasks to be completed.
Your task list is a great resource for pointing people in the right direction. But what are you pointing them to? You'll need a handy set of how-to docs to help new hires help themselves.
Get started with our how-to blueprint – it gives you the basic layout so you can focus on adding content.
Label all your onboarding docs with the same label, like "onboarding", or something similar. With all your docs labelled, you can create a central repository of them using the content by label macro.
Make sure to add images, code blocks, and links to relevant web content to your page.
After you've completed your page, you'll notice the Content by Label macro at the bottom. This macro automatically pulls in all the pages in the current space with the same label.
Once the page is saved, you can see a dynamic list of pages with the same label:
2. Application and network architecture documentation
These documents need to be accessible to the whole team, at all times. Here's how to put together your architecture docs in Confluence:
Use diagramming tools to embed architecture diagrams. There are two great add-ons available in the Atlassian Marketplace that are perfect for this: Gliffy and Draw.io. Both these add-ons give you a diagram editor right within Confluence. We use these tools as well as websequencediagrams.com for simple relational diagrams that you can attach as images.
The most important part of your architectural docs is being able to reference diagrams, components, SDKs, APIs and related docs all in one place. These documents can be as heavy or light on information as you need. At Atlassian, we put all this information in tables. Tables are easy to insert into your page, and flexible. Use the table tools menu to add and cut columns and rows, merge, and highlight cells.
Just like your onboarding content, you'll want to label all your related architectural docs to keep them organized.
3. Release process documentation
The other important set of documentation you'll want to create and store in Confluence is your release process and readiness docs. These are the documents that streamline your releases and help build a culture of continuous improvement, and are probably constantly evolving as you adopt new practices to improve your process. So you'll want to make sure everyone has access to the latest n' greatest – which is exactly what Confluence was built for.
There are three key elements to your release process documents:
- Continuously refresh and improve – Every release should serve as a learning process for your team. As you improve your development velocity and release cadence, you'll want to keep your docs up-to-date. We use the info macro as a visual indicator of the page's relevance.
- Organize related docs – You'll want to document the relevant stakeholders, potential workarounds, and all the necessary comms that go out before and after a release. At Atlassian, we use separate child pages for all of this information. To show all of these related pages, add the children display macro to the top of your page. This macro shows all the subpages of your homepage, so you have quick access to the page you need.
- Visualize the process - Team Calendars is an add-on for Confluence, made specifically to help teams track team leave, JIRA releases, and events in one place. Embed a calendar on your release readiness page to give everyone visibility into your release dates and avoid conflicts by seeing the whole team's availability on those dates. You can view by month, week, or on a timeline.
At a glance: what did you just learn?
Having a rich, reliable, centralized set of technical documentation might not be the sexiest aspect of your development team, but it can help your team move faster and go from good to great. Here's a quick recap of what we covered:
- Page tasks - Create an onboarding task list for all new hires
- How-to article blueprint - Use the included how-to article page blueprint to quickly document important development how-to guides
- Content by label macro - Group all the pages with the same label
- Diagramming add-ons - Create, edit, and share diagrams right within Confluence
- Code block macro - Embed code snippets from any programming language into your page
- Children display macro - Show all the child pages that are organized under your parent release process page
- Info macro - Add a visual callout at the top of your page
- Team Calendars add-on - Visualize release dates, team leave, and other events on one calendar
This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.
Hungry for more?
Download the Software Team’s Guide to Confluence ebook to see all our tips in one place, then watch the blogs in this space to get notified when new tips articles like this are posted. And if that's still not enough, sign up for Confluence Insiders – our monthly newsletter covering all things Confluence.