Software is software, and it just works, right?
Well, for anyone who has ever had to find an online help center to read through a knowledge base to troubleshoot an issue, only to find nothing and have to go to Reddit or some forum that hasn't been updated since 2016, you know that just isn't true.
Software documentation is useful for a variety of reasons. It can help end users learn how to use the software or how to troubleshoot problems. It can help developers know how an application works under the hood so they know how to integrate their own apps with it. It can help everyone know what the purpose of the software is, how to use it, and how not to use it.
All of that documentation needs to be written, and while it's often the developers themselves tasked with writing it, many businesses have taken to hiring technical writers to do it for them.
So, how can you create software documentation, and what does it look like when you do?Let's find out!
Software documentation is written information on how to use or interact with a piece of software. There are many types of software documentation, largely defined by their purpose, audience, and format.
Software documentation is not comments in code. Code comments are helpful for developers, but they're inaccessible to everyone else, so while they serve a similar role, they aren't the same thing.
Software documentation can be broken up into roughly six different kinds of documentation. There's some overlap, and sometimes one document can serve more than one purpose, but here's what you might be looking at.
1. Project Documentation is documentation about a software development project. It's used in the creation and development process of the software and can include items such as technical design documents, wireframes, project plans, and technical specifications. It's a combination of guidelines for developers to follow and goals for them to reach.
2. Process Documentation is another form of documentation used by the people creating the software in question. It includes documents such as a development plan and roadmap, a testing plan, release schedules, and bug reports. Unlike project documentation, process documentation is generally used beyond the release date of a product and includes details about ongoing support and development efforts.
3. Product Documentation is documentation meant for the end user of the software. When you open a new piece of software and find a PDF of instructions, that PDF is product documentation. This kind of documentation often includes user guides, installation guides, and reference manuals for the product. For example, here is Google's documentation for using Google Ads to create an ad.
4. Technical Documentation is documentation about the technical aspects of a piece of software. This documentation details things like data structures, API information, README documents, and system architecture guides. This is most used by other developers who need to interface with the systems in place. Here's an example of Google Docs's API documentation.
5. System Documentation is documentation designed to teach high-level users, administrators, and power users about the ins and outs of a system. This usually falls short of technical documentation but is more detailed and in-depth than product documentation. It can include things like detailed user manuals, architecture documentation, and troubleshooting guidelines. These days, you often find this information in knowledge base wikis.
6. User Documentation is the documentation created for users, and often by users. User-created tutorials, reference documentations, "cheat sheets," and other documents that are helpful for users in real scenarios rather than the scenarios planned by the developers all fall into this category. Proactive companies can create these documents, but many rely on their power users to do so.
The actual process of creating software documentation is relatively simple. It requires a keen mind and a lot of attention to detail, as well as an understanding of the underlying systems and the target audience. Someone who has no idea how the software works can't really write effective software documentation for it, after all.
The first step in creating software documentation is starting early. In fact, creating software documentation should be part of the development process from the moment the project is conceived to post-release support.
As such, your technical writers and documentation creators must be closely involved in the project from day one.
For each kind of documentation, the writer must know two things. The first is, of course, what kind of documentation it is. There's a pretty big difference between writing technical API guides and writing a more casual user tutorial.
Defining the audience is also important. There are a few key attributes that your technical writer will need to know, such as:
Pinning down these details can help a lot with the documentation creation process.
The format of a piece of documentation can be important for how it is presented.
These days, the two most common formats for software documentation are PDF guides and wiki knowledge bases. PDF guides are more static but can be downloaded and referenced (or even printed out) by the people meant to be using them. They are formatted more like traditional user manuals and guides, and in fact, many are identical to printed guides of yesteryear.
Wiki knowledge bases, on the other hand, are more distributed, interconnected, interlinked, and "living" in their own way. Knowledge bases change and grow as more information is needed or requested. They're easier to edit and keep up to date, but they aren't able to be downloaded and easily accessed offline if the need arises.
Knowing what kind of format the documentation will take is an integral part of creating it properly.
This may or may not be necessary, depending on how many technical writers you have creating your documentation. A style guide is an important part of maintaining consistency across your documentation, so if you're going to be creating documentation with more than one technical writer, it can be a good idea to define the style.
Elements of a style guide can include:
A style guide can be a simple one-page document of guidelines, or it can be an elaborate brand guidelines page. Here's an example of the latter from Microsoft.
Few forms of writing require as high a level of precision as software documentation. Only engineering documents and things like fabrication guides need to be more precise. That means things like terminology, references, order of operations, and other details all need to be defined and adhered to for consistent documentation. A technical writer lacking this attention to detail is an ineffective writer.
Keeping your documentation simple and effective is usually the way to go. Always provide avenues for a reader to dig deeper as necessary, but avoid front-loading complexity on audiences who likely won't need it.
In the majority of cases, software documentation is a living document. Even in cases where a manual is published in PDF form, it should have a clearly labeled version number and publication date, with revisions published as necessary. Wiki-style knowledge bases should have "last updated" dates clearly visible.
This serves two purposes. The first is to increase trust in your documentation. A user who needs help is going to be more satisfied with instructions updated in the last year than they are instructions from five years ago, even if the five-year-old instructions are still valid.
The second is to ensure that your documentation is as updated as much as possible. Any time anything changes, whether it's a business process, a piece of the API, or a data structure, it needs to be edited and updated into the documentation when the change goes live.
You may also need to maintain more than one version. For example, Google's switch from Universal Analytics to Google Analytics 4 means that, while both versions are supported, they have documentation for processes that differ in both versions.
Hiring a technical writer at the start of your project and working with them throughout the development of your software can ensure the most robust, complete, and detailed software documentation possible. However, a lot goes into hiring the right kind of writer, and it needs to be done as early as possible for the best results.
In my guide on hiring a technical writer, I go over the steps.
Finding technical writers isn't necessarily difficult, but finding a good technical writer you can trust to handle your software documentation can be a little harder. You can always look on sites like Upwork or Freelancer, or you can post a job listing on my job board. Unlike other forms of writing, agencies aren't as common, while hiring writers as actual employees is more common than freelancing. Regardless, the important part is finding the right kinds of writers so you can proceed to testing their skills.
Once you find technical writer candidates, you can give them a test. Develop a complex passage, API, or even give them access to your software and ask them to create documentation to achieve a specific goal. For example, you might ask for a tutorial on how to perform a task (giving them the basic steps to do it so they aren't completely lost) or give them a set of API data tags and their definitions and ask for documentation for that section of API.
From there, you simply see what the writer produces and judge it based on what your needs are and how it compares to other documentation provided by competitors. Once you find a writer who can produce what you need the way you need it, you can lock them in with a contract and keep them on staff or on hand to create all of your documentation. We wish you the best of luck!
How to Write a Press Release (With Guidelines and Examples)
How to Write the Perfect Product Review (With Examples)
How to Create a Guest Post Guidelines Page (With Template)
20 Technical Writing Examples for Training and Inspiration
How to Create a Content Calendar Template in Google Sheets
How to Hire a Writer to Create Online Course Content
[Guide] How to Find and Post Online Editing Jobs in 2022
How to Self-Publish a Book on Amazon (The Right Way)
How to Identify and Choose the Best Author Writing Style
[Guide] How to Hire Somebody to Write Your Email Newsletter
We encourage you to share this article on Twitter and Facebook. Just click those two links - you'll see why.
It's important to share the news to spread the truth. Most people won't.
