How to write helpful software documentation

This article will provide tips for writing effective software documentation. We will cover how to ensure that your team is aligned on using the same documentation and how to onboard new team members leveraging your documentation.

Topics:

• Aligning with the business requirements
• Collaboration
• One source of truth
• Integrate with task management software
• How do I get my team aligned to use the same documentation?
• Tips for Writing Effective Software Documentation

Aligning with the business requirements

The goal of writing software is to solve problems. Solving problems requires information. Information needs to be stored such that your team members find it fast.

In a typical software development team, there’re several stakeholders.

• A business client (or a product owner).
• A project manager (or a scrum master).
• Engineering team.
• Design team.

All of the stakeholders above are working towards one goal. It’s to solve a real-life business problem and serve customers through the piece of software being built.

In my experience, the best software documentation aims to align people from the same team and increase collaboration with the other teams. Meanwhile, software documentation that purely focuses on the technical details usually is never actually used to develop and often gets forgotten.

Another way to visualise how helpful software documentation functions within an organisation is to look at it from above as a river.

The river can have multiple smaller branches or even other rivers that flow into it. But it’s constantly flowing towards the sea.

Similarly, software and its documentation should integrate other sources like documentation from the design team and flow towards releasing software that solves real-life customer problems.

In contrast, poor software documentation visually looks like a static lake where you feel like you could drown in the technical jargon.

I find that excellent software documentation focuses on these things:

• Integrating documentation from other stakeholders (product, design).
• Puts delivering features for users as the priority.
• It doesn’t abstract business problems with technical jargon, making reading it more challenging than needed.
• They keep things simple but actionable and helpful.
• Helps onboard new team members.

After looking at this larger picture, we can look at lower-level, more tactical things we can do to integrate software documentation within a team.

Collaboration

I find it helpful to use documentation tools that allow commenting and editing by other team members. It’s essential that everyone on the team can contribute to the documentation.

One source of truth

In my experience, tools like Google Sheets and Docs are great for short-term alignment but are bad for long-term documentation as they easily get lost in Google Drive.

Integrate with task management software

Having your tasks and documentation in one place enabled better team productivity. My favourite ones are Notion and Atlassian tools like Confluence and Jira.

How do I get my team aligned to use the same documentation?

It’s easy to see the idea documentation setup from the birds-eye view. But what do you do if you find yourself in a poorly documented project and when other stakeholders don’t document their part?

What has helped me in such cases is to start with myself. Start documenting things you are responsible for.

In my case, as front end developer, I would.

• Document practices for using API consumption layer. How to cache and invalidate asynchronous data.
• Document managing global client state.
• Document UI Components
• Ensure the code architecture and file naming matches the backend codebase and Figma design files.

After I do this initial work, I’d be better positioned to convince other team members that they should document their work through the results we would see with the other front-end colleagues.

Tips for Writing Effective Software Documentation

I find these tips helpful to make write better documentation.

1. Know your audience: Before I start writing, I ensure I understand my audience and needs. This helps me tailor my documentation to their needs.
2. Keep it simple: I use plain language and avoid technical jargon and acronyms as much as possible. This makes my documentation more accessible and easier to understand.
3. Provide context: I ensure my documentation provides enough context to help my audience understand the purpose and function of the software. I provide examples and use cases to help illustrate how the software works.
4. Use visuals: I incorporate screenshots and diagrams to help illustrate key concepts. This makes my documentation more engaging and easier to follow.
5. Organize effectively: I use headings, subheadings, and bullet points to help organize my documentation. This makes it easier for my audience to find the information they need.
6. Be thorough: I ensure my documentation covers all the key features and functions of the software. I don’t assume that my audience knows everything about the software.
7. Use a consistent tone and style: I use a consistent tone and style throughout my documentation to help maintain clarity and readability.
8. Provide links and references: I provide links to additional resources and references to related documentation. This helps my audience find more information and deepen their understanding of the software.
9. Update regularly: I update my documentation to reflect changes and updates to the software. This ensures that my audience has access to the most up-to-date information.
10. Solicit feedback: I ask for feedback from my audience to help improve my documentation. This helps me understand what is working well and what needs improvement.
11. Add the original source: Often, when I write documentation, I get inspiration, or I outright copy some parts of articles, videos or other people’s documentation. I always try to add links to the source in case the person reading the documentation can explore the topic further or if that source can offer a better explanation than I did through my documentation.

By following these tips, you can write software documentation that is accessible, thorough, and effective.

How I onboard new team members using written documentation

In my experience, no matter how good you think your documentation is, what matters is whether new joiners to the project can read, understand, and ship features using it.

When I write extensive software documentation, I know that it’s likely that I’ll need to have a one-on-one meeting with a new joiner to walk them through the documentation together.

This is an opportunity to check my documentation writing skills. I try to avoid over-explaining the documentation and see if the person can understand it first. If they need clarification, we delve as deep as we need to into that topic, but I try to see if the documentation is good enough so they can read it themselves if they have to. I look for bottlenecks together and improve the documentation based on their feedback.

Tools for Creating Software Documentation

When choosing documentation software for collaboration, integration, and easy maintenance, it is essential to consider the following factors:

1. Collaboration: Look for software that allows multiple team members to collaborate on documentation. This may include features like commenting, version control, and real-time editing.
2. Integration: Look for software that integrates well with other tools and platforms that your team is already using, such as project management software, version control systems, and chat apps.
3. Ease of maintenance: Look for software that is easy to maintain and update over time. This may include features like version control, automated backups, and easy-to-use editing tools.

By considering these factors, you can choose a documentation software that is well-suited to your team’s needs and helps you create effective software documentation.

Here are some tools that have worked for me to make the process of creating software documentation easier:

Notion

Pros:

• All-in-one workspace for organizing and collaborating on documentation.
• Customizable templates for different types of documentation.
• Integrates with other tools like Slack and Google Drive.
• It can create advanced automation, nested pages, and knowledge databases.

Cons:

• In my experience, the flexibility of Notion can sometimes be its biggest limitation. It’s easy to get lost in all the options and settings and spend more time tinkering around than writing the documentation.

Atlassian Confluence

Pros:

• Designed specifically for creating and sharing software documentation.
• Integrates with other Atlassian tools like Jira and Bitbucket.
• Customizable templates for different types of documentation.

Cons:

• Limited customizability compared to other tools.
• It can be expensive for larger teams.

Google Docs

Pros:

• Good pricing.
• Easy to use and share with others
• Integrates with other Google tools like Drive and Sheets
• Great for documentation that’s meant to be used by multiple stakeholders, as most non-technical team members are familiar with Google Suit tools and workflows like comments, sharing and editing.
• Most teams use it by default, so the pricing is not an issue because Google Suite is already used for video calls and email, and your team won’t need to buy additional tools.

Cons:

• Limited customization options
• Not designed specifically for software documentation
• The user experience for viewing and editing docs is not as good as in tools like Confluence or Notion

Conclusion

Documenting software can be challenging, but it is essential for development and team collaboration speed and experience.

Key takeaways:

• Align your documentation across the whole team, not just the engineering team.
• Your documentation should enable faster feature development, better developer experience and easier onboarding for new team members.
• Avoid using technical jargon where it can avoid.
• Make sure you use the same language to describe the business case concepts as the rest of your team.
• Pick tools for documenting that easily integrate into your current workflow.
• Pick tools that enable collaboration through live editing, commenting and sharing.
• Actively seek feedback on your documentation from your current colleagues or new joiners to the team. When gathering feedback, try to get their first impressions first before over-explaining.

Thanks for reading! I hope this was helpful. See you next week.