Freelance Writing Jobs
Post a job

How to Create Software Documentation (With Examples)

By:
Shaun Connell
 Updated
January 21, 2023

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.

Solution So, how can you create software documentation, and what does it look like when you do?

Let's find out!

What Software Documentation Is (and Isn't)

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.

Windows 10 Software Documentation

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.

Types of Software Documentation

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.

Types of Software Documentation

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.

How to Write Software Documentation

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.

1. Start Early

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.

Starting Software Documentation Early

As such, your technical writers and documentation creators must be closely involved in the project from day one.

2. Decide the Kind of Documentation and Audience

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.

Deciding the Kind of Software Documentation

Defining the audience is also important. There are a few key attributes that your technical writer will need to know, such as:

  • Is the audience internal or external? Internal audiences will know something about your business and its processes, architecture, and more. External will not.
  • Are they technical or layman? Technical users expect documentation that covers advanced topics and provides all of the relevant information so they can figure out anything that isn't spelled out. Casual users might not have any idea what most of that means and just want simple, plain English user guides.
  • Are they working on the software or using it? There's a large world of difference between documentation meant for developers and documentation meant for end users.

Pinning down these details can help a lot with the documentation creation process.

3. Define the Format

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.

PDF Guide Software Documentation

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.

4. Create a Style Guide

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.

Creating a Style Guide

Elements of a style guide can include:

  • How you reference your own company and software. Standardized references help a user maintain awareness of what the documentation is trying to tell them.
  • Tone and voice. All writing, even technical writing, has voice, tone, POV, and other details. Knowing what they are and ensuring that they're consistent throughout your documentation can be important.
  • Elements of style. Even little details, like whether or not you capitalize certain words or use dots in acronyms, need to be consistent. You might pick something like an AP style guide to base your style on, or you might develop your own house style.

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.

5. Maintain Attention to Detail

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.

Writing Software Documentation

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.

6. Keep it Alive

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.

Multiple Versions of Software Documentation

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.

Hire Professional Technical Writers

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.

  • Determine your needs for software documentation according to the steps listed above. Knowing what you need helps you define the scope of the project for a freelance writer, or hire a technical writer as an employee knowing what they're getting into.
  • Find a writer candidate with a great command of language and attention to detail. Make sure they can take complex passages or data and distill meaning out of it in a compelling and accurate way. Ideally, you will also find a writer candidate with experience as a developer or working with developers to create documentation in the past.
  • Don't be afraid to look for more than one writer or go through and test multiple writers before you settle on the best one. Hiring a technical writer is a lengthy process, and since they're critical to your project, you want to make sure you're getting the best.

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.

Freelance Writing Job Board

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!

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.

Written By:
Shaun Connell
Shaun Connell has spent his entire career either working as a freelance writer or hiring freelance writers for his many successful publications. Shaun has learned the exact tricks of the trade to hire the perfect writer for almost any niche.

Leave a Reply

Your email address will not be published. Required fields are marked *

Writing Jobs Newsletter
Subscribe to receive information, free guides and tutorials