Software documentation tools come in all shapes and sizes.
With so many options to choose from, it isn’t surprising that software development companies have a tough time selecting the right tool for their needs.
Ultimately, the best tool for your company will depend on the size and characteristics of your team, your documentation needs, as well as the nature of the products you’re building.
That being said, there are some must-have features all good software documentation tools have in common, and in this article, we’re going to explore every one of them.
Read on and find out which features you shouldn’t do without when choosing a documentation tool.
Import/Export
When most companies decide to implement a documentation tool, they most likely already have an archive of important documents that will stay valid even after the switch to another platform is made.
Luckily, quality documentation tools come with import/export functions that make it easy for knowledge managers to relocate their entire archive into a new system.
Software-oriented documentation platforms also support formats such as Markdown, OpenAPI, and many more, so you can import various types of documentation, not just regular text docs.
For example, here’s what Archbee’s import function looks like. Notice that it has the ability to import code (OpenAPI) as well as textual documentation.
Exporting files is often equally important. There are several situations when you might need to provide access to software documentation outside of its knowledge base, such as:
- Working offline or in the field
- Downloading and sending parts of your knowledge base to investors, outside contractors, or potential customers
- Including hard-copy documentation with a physical version of the product for sale
A good software documentation tool will usually be capable of exporting individual documents in PDF or Markdown format, so it’s instantly ready for use.
More advanced software will also allow you to download entire workspaces or knowledge bases as Zip files and email them to a chosen participant. Archbee can do both.
Good software documentation tools should be flexible.
They should allow you to import old documents into the tool, as well as export documents for circumstances when you don’t have access to the knowledge base.
Search Function
How do you approach software documentation?
Do you read it in a linear fashion, like you would a book, or do you only read segments that will answer your current questions or solve a problem you’re facing?
Users (both internal and external) mostly follow the latter option, meaning they need a resource to help them find the information they need instantly and without much browsing.
Search bars are exactly that resource.
You’ll notice that the search bar is positioned very prominently at the top of the page.
This reflects the fact that most users will look for this feature to input their questions and problems and quickly find the information they need.
Of course, the entire knowledge base is also organized into categories (below the search bar) to accommodate users who want to browse through the documentation to learn more about the software.
So you’ll need to work continuously to improve the search function of your knowledge base.
For example, make sure you pick a tool that will allow you to add tags to every one of your articles to help the search software easily identify what the article is about and offer it to users searching for exactly those topics.
The search function might just be the most important feature of a knowledge base because it’s what makes using the base fast and efficient.
So be on the lookout for software with advanced search functionality.
Document History
From the perspective of knowledge management, being able to access previous versions of a document is essential because it prevents you from losing important information due to a mistake and enables you to get an overview of how a document has evolved over time.
And the feature that allows users to access these previous versions, see which edits were made, and, if need be, revert to older versions is called document history.
Here’s what that feature looks like in Archbee:
Quality software documentation tools will enable you to update documents as often as you need, publish new versions, and retain the old ones so that you can access them when you need to.
They will also let you highlight the changes so that you can see exactly what’s different in each version.
Last but not least, as you may have noticed in the above screenshots, good documentation software will also show you which team members made the changes to the document.
This is a handy function because it can help you establish a chain of responsibility for documentation.
For example, it will enable you to ask a team member why a particular change was made if you don’t understand it or if it seems like a mistake.
So, in a nutshell, document history is the feature that helps you retain control over the development process of the documents in your knowledge base.
Every change will be noted, and visible and older versions of documents will never be lost.
Single-Source Features
Single-sourcing documentation means applying certain principles to the way you create your documents to make parts of them easy to reuse in different contexts and translate into other languages.
This methodology is used predominantly in large companies with many products that are similar to each other and therefore need very similar documentation, as well as support in multiple languages.
However, any company can benefit from the principles of single-sourcing, even software startups.
For example, in situations when one set of instructions needs to be reproduced in a troubleshooting guide when it was initially created for the product’s getting started guide.
So how do single-sourcing features look in a documentation tool?
You’ll often find them in the form of “reusable content” options that allow you to single out pieces of content and save them as blocks that can be easily inserted into any document you’ll create in the future.
Within Archbee’s software, this feature is called content snippets.
Here’s how it works:
Source: Archbee on YouTube
This is a great feature for helping technical writers work quickly and with a reduced margin of error.
Even if you’re only working on one product at your company, your technical writers will thank you for choosing a software documentation tool with single-sourcing capabilities.
Integrations with Other Tools
In a typical software company setting, teams use software tools for communication, project management, software development, whiteboarding, scheduling, and much more.
Oftentimes, you’ll want to include materials from those tools within your documentation so that you have a single source of truth for everything your company does.
With an integration feature, you’ll be able to do that in a couple of clicks.
Mind you, every tool will have integration capabilities. The question is how many and which ones.
For example, Archbee integrates with the most popular tools for all the tasks mentioned in the first sentence of this section.
Let’s look at an example of an integration that’s very valuable for software development: the OpenAPI Swagger integration.
Developers use this set of tools to build and consume REST APIs.
The APIs built this way exist as a separate file format which, thanks to the Archbee integration, can be uploaded into an Archbee document.
Once uploaded, the file turns into a fully useable Swagger interface you can continue working with inside the document.
Take a look at how easy the process is in this short video:
Source: PitchGround on YouTube
As you’re designing, building, marketing, selling, and updating your software products, you’ll be using an entire technology stack to do your work.
Thanks to integration features, you’ll be able to document all of those processes in one place: your software documentation tool.
Access Control
The documents in your knowledge base will contain various information about your software products.
Some of it will be available publicly, and some of it will be confidential.
Some of it you’ll want to share with investors, subcontractors, and potential customers, and some of it will have to stay internal to your organization.
Access control is a feature that will allow you to decide who can view your documentation.
That’s a very useful feature to have if you want a layer of security for your software documentation.
Most documentation tools will allow you to decide if your documentation can be viewed by the public or just your team members.
Here’s what a public software knowledge base looks like:
A public knowledge base is easily accessible online. All you need is a web browser and the correct address.
Internal documentation is also accessed online, but you’ll need credentials to get in.
More advanced documentation tools will also give you the option of sharing documents from your internal knowledge base with outside parties, without making the base public.
Archbee offers several options for doing this.
So, apart from unrestricted and password-enabled access, you can also create guest accounts, generate magic links (links that only the owner of a specific email address can access), and provide JWT visitor authentication (access with a specially created Json Web Token which is a method with added security).
Information security is paramount when you’re developing software products. With this feature, you’ll be able to keep your documents safe, so look for software with various methods of access control.
Collaboration Features
Good software documentation is never created in isolation.
Team members across different departments can contribute to the documentation process to make the results more accurate, up-to-date, and easy to consume.
For example, technical writers will often ask subject matter experts (SMEs) for input on the technical aspects of a document they’re writing or ask managerial staff for approval on certain details.
This collaborative aspect is often considered a difficult part of the technical writer’s job simply because it can take a lot of effort to chase down team members and get them to allocate time for reviewing documentation.
So why not make your technical writers’ job easier by investing in a software documentation tool that facilitates collaboration and encourages team members to work together on documentation?
Quality documentation software has plenty of features that enable collaboration.
For example, commenting options allow you to communicate directly inside the document, making it unnecessary to use Slack or other tools to work on a document.
Some tools also have tagging or mentions features that are useful when you want to direct team members' attention to a document in the knowledge base.
In fact, advanced tools will even let you assign documents for verification by other team members.
In Archbee, this feature is particularly useful because documents will be marked as unverified until the assigned person reviews them and confirms the document is accurate.
That way, the likelihood of publishing an inaccurate or outdated document is significantly reduced.
Take a look at the feature in the video below.
Source: Archbee on YouTube
Collaboration is a sensitive matter where software documentation is concerned.
But you can make it much easier and even enjoyable if the tool you’re using for documentation offers ways to work together in the docs.
Read recommendation: Benefits of Software Documentation Tools
Conclusion
Selecting the best software documentation tool features isn’t as easy as picking the product with the best design or the most intuitive text editor.
Other considerations you should take into account are formatting capabilities, ease of navigation, collaboration options, and integration features, just to name a few.
Archbee was built with all the needs of your team in mind, so sign up for a free account today and start creating accurate software documentation more efficiently.
