Software documentation is a staple of good project management.
It helps your team keep track of the big picture, it optimizes onboarding and it’s a constant reference point for any obstacle in your development process.
Yes, it’s primarily an internal document.
But most software documentation will morph into an external reference as well.
What you need to keep in mind is the purpose of such a document: helping people uneducated about your product get started using or developing it.
Sounds like something you’d like to do?
Here are seven tips on how to improve software documentation.
Watch your Writing
Writing software documentation is hard.
You’ve got diagrams, code snippets and changelogs to keep in mind.
So you can get overwhelmed and forget all about the instructions themselves.
But that’s a dangerous pitfall.
The quality of your writing is just as important for software documentation as it is for lead magnets or blog posts.
For better writing, there are a few things you can tweak.
First of all, put clarity above everything else. Technical terms are a must in any software documentation, but try to create a learning curve for new team members to get accustomed to your tool.
Remember that software architects and programmers aren’t the only people who will read software documentation - marketers and customer support agents might need to go through it as well.
However, you should always balance clear writing with a clear structure so that experienced users can find the specific section they need if they’re in a rush.
How do you go about it?
It’s a matter of asking the right questions.
For new team members, ask yourself “Is this section/paragraph/sentence clear enough so that non-tech savvy people would understand it with minimal knowledge?” or “Can I summarize this information using simpler terms?”
For experienced users, think “Is this section/paragraph/sentence exhaustive?”.
If not, add value.
Go deeper.
This is an exercise of balancing manner and matter. The matter (or content) should be comprehensive, while the manner of your presentation should be as simple as possible.
Don’t assume previous knowledge, add explanations for complex processes or in-house workflows and only use acronyms if you’ve explained what they mean (in writing!) beforehand.
Lastly, avoid passive voice.
It’s easy to “have a piece be written” in passive voice because it comes naturally to the human brain.
However, it can lead to some confusion. It’s important to determine which agent does what in software documentation, which variable fits where and so on.
Passive voice tends to mess that up because when you’re dealing with a lot of stakeholders in any process, you need clarity - who acts upon what.
Not to mention, passive voice is cumbersome to read.
That’s why you should use active voice whenever possible.
But good writing is only the first step in how to improve software documentation.
Clear Formatting and Structure
Formatting and Structure are key for good software documentation.
That’s because the document needs to make sense for an uneducated audience but it should also help experienced users navigate their way quickly to find solutions.
To make sure you get it right, start with categorizing your information.
You should have sections and subsections for each feature, process or unique set of data.
For example, you could outline the overall description of your software, follow it with the main features or architectures, then finish it up with separate sections for depositories and integrations.
More importantly, you should always start with a journey in mind.
Walk users through the things they’ll have to know, from most to least important.
For that, an Onboarding section could help. Archbee features that for their external documentation.
But it can also help bring new team members up to speed.
For the formatting itself, use clear headlines (Markdown can help) and don’t forget about bullet points.
To understand the importance of bullet points, compare these two sets of data:
What can you expect from using Archbee?
- Build a solid knowledge base that your team can use to scale easily, onboard new members faster, become remote-friendly, and provide better workflows overall;
- Build a great documentation site (product docs) for your customers;
- Integrate it with great SaaS solutions that you might already be using.
What can you expect from using Archbee?
You can build a solid knowledge base that your team can use to scale easily, onboard new members faster, become remote-friendly and provide better workflows overall. You can also build a great documentation site (product docs) for your customers. On top, you can integrate everything with great SaaS solutions that you might already be using.
Bullet points convey information in an organized manner. As you may realize, this is extremely important for new releases info.
Lastly, employ the reperformance standard.
What does this mean?
Your software documentation tutorials should be replicable.
You should edit your documentation from the perspective of an uneducated audience - Could such a person replicate the processes outlined in the document?
If so, you’re good to go.
Target Audience Analysis
Whether you’re writing for an internal or external audience, you need to keep in mind who will read the documentation.
If the documentation is going public, use your (hopefully already existing) buyer persona to determine what you should cover.
To put this in practice, think about Wordpress’ documentation in comparison to Python’s documentation.
The first is geared towards a big audience, many of whom are not fully-fledged webmasters, but they do need to provide help for users that want to integrate with complex APIs.
Python’s the other way around. Most users are developers with advanced programming knowledge, but it’s also a simple language that is often picked up by newcomers to the medium.
Both companies keep this in mind when writing, and it can be seen in their documentation.
Wordpress starts you with the easier stuff then goes into more complex topics. Python has some articles geared towards beginners, but the bulk of their documentation is made out of depthful tutorials.
Always be aware of your target audience and write for them.
Internal documentation shouldn’t be any different.
Keep track of your team members and their needs or technical knowledge.
Got that squared away?
Great, time to write for them.
But how do you go about it?
Ray Edwards is a master of copywriting. He’s regarded as one of the experts on the topic and his ways are a bit unorthodox (but efficient).
To tap into his writing wisdom, you could try a simple exercise.
Before laying anything on paper, close your eyes and pretend you’re the person about to read what you’re writing.
Think about their day, struggles and try to envision every step of their experience.
As soon as you open your eyes inspiration is bound to flow.
This is one of the ways you can get in the shoes of your target audience or team members to better write something they’ll need.
Great Visuals
Good writing is never enough.
The purpose of software documentation is to help people understand your processes and tools.
Visuals are just as important for this goal.
Start with multimedia.
Informative and helpful images are extremely important because it’s one of the quickest ways to showcase what you’re explaining.
But don’t stop there and don’t be afraid to use gifs, videos or even infographics. If you’re running on a budget, tools like Canva can help you bootstrap something.
But visual clarity is just as important.
Images are one thing, but what do you do when you need to showcase code snippets or architecture diagrams?
Having a comprehensive Wiki helps your team by outlying the complex parts of your development process.
Tools like Archbee or Typora can help in this area.
Say you’re commenting on a code snippet or specific directory.
Instead of just pasting it along with regular text, try to highlight the section. It sounds like a small detail, but it can make a lot of difference.
For experienced users because they can quickly navigate on-page and locate what they’re looking for.
For newcomers because the information is easily “transferable” to their brain when segmented visually.
Default to Simplicity
This is more of a mindset tip.
You’re not aiming to impress your college creative writing teacher. The purpose of software documentation is to help people work better.
Regardless of the element - text, images, formatting or code, whenever there’s a simpler alternative go for that.
However, don’t mistake unnecessary complexity with specificity.
Specificity is important because saying “problem with Javascript” is not the same as saying “There’s a bug in this minification because the output is wrong”.
What I mean is, don’t say “The algorithm output is incorrect, which can suggest the likelihood of a code error in the minification section” when you can just write “There’s a bug in this minification because the output is wrong”.
This is extremely important when it comes to inexperienced users. If you know a thing or two about Javascript, you won’t need to Google “class”, “compiler” “algorithm” or “argument”.
However, if users don’t eat Js for breakfast, don’t have them struggling when the message can be sent using less technical terms.
Yes, they’ll need to learn the terms at some point.
But you ensure higher retention of information when you give them new terms to learn gradually.
Tools Count
There are a lot of free and paid tools to help you both write and host software documentation.
Regardless of your choice, there are a few criteria you should keep in mind when it comes to choosing a tool to help on how to improve software documentation:
- All in one place. Formatting, editing, and hosting, the more in one place the merrier.
- Knowledge base. You should be able to organize a knowledge base using the tool.
- Collaboration. Project managers and developers should be able to work together on the platform to constantly improve documentation. Everyone else should have access to it.
These are the hallmarks. From there on out it’s a matter of pricing and preferred features.
If you don’t want to do the research, here are some of the best on the market (and who they’re good for).
- Swagger. Great for developing APIs. They go beyond documentation too.
- JavaDoc. Good if you’re working with Javascript.
- Archbee. Great for developing an exhaustive internal Wiki that can easily be shared externally.
- Huddle. Great for general document collaboration.
The list could keep on going. A lot of software development niches have their own documentation tool.
Regardless of your choice, make sure you factor in user reviews, as well as your individual needs.
What language do you work with?
How big is your team?
Do you want to use the tool for internal as well as external documentation?
Analyze the market and make sure you choose according to your enterprise’s needs.
Here are two read recommendation related to software documentation tools:
1. 7 Common Features All Good Software Documentation Tools Have
2. Benefits of Software Documentation Tools
Style and Tone
Lastly, remember that any document (internal or external) is as much a part of your identity as anything else.
Team members and customers will associate documentation with your business.
So it’s important to focus on writing style and tone.
The technical writing paradigm is pretty strict - content should be impersonal, extremely actionable and filled with jargon.
That works, because documentation is a process enhancing aspect before anything else.
And you should definitely stick to the formula if your message is professional. However, you shouldn’t be afraid to tweak it.
What you should aim for is uniformity. If your blog posts leave room for a joke or emoji here and there, it could work for external documentation as well.
If your internal documents are powerfully color-coded and acronym filled, emulate that in your software documentation as well.
This goes beyond just writing too.
The syntax, for example, should be just as uniform and consistent.
Aim for a common writing guide, especially for bigger teams, and use it for software documentation too.
For example, Archbee is a big fan of emojis, so you’ll see them in our software documentation.
This is important because whenever someone interacts with your identity, they’ll create (or reinforce) an image they have about your business.
Be aware of that and you can tell the right story to the right audience.
To Wrap It Up
Software documentation is about improving your processes.
Getting new team members up to speed, solving an expert’s quick inquiry or onboarding clients on your product.
If that’s hard to cover all at once, take it step by step and follow these tips:
- Write better, avoid passive voice and default to clarity.
- Outline your users’ journey and formulate a clear structure for your documentation.
- Analyze every person that’s going to read the document and write the text they need to read.
- Create informative, helpful and beautiful visuals.
- Simple is better than complex, but not mutually exclusive with specific.
- Get yourself the right tools for the job.
- Maintain a consistent style and tone.
Lastly, this is not an exhaustive list.
Start with them in mind, but find what works for you and innovate at every step.
How do you go about improving your software documentation?
Did you find our tips on how to improve software documentation helpful?
