Types of Software Documentation

Paperwork can be an annoying distraction from your real job. Software documentation in software engineering, however, is an essential part of writing good code. No matter how clear and simple you think your software is to use, you'll need to provide some types of user documentation. If there's no documentation, potential users may give up on your programs and hunt for software that comes with how-to instructions.

The different types of program documentation all serve the same purpose: to make it easier for users to understand the program and use it to get something done. This includes coworkers as well as customers. If your company employs proprietary software, providing new employees with different types of user documentation speeds up their onboarding.

User documentation offers other benefits:

• You know your own work inside and out, but six months or a year from now, other projects may have obliterated some of your memories. User documentation helps your future self use your work without relying on memory.
  
  
• You know that users have a consistent experience working with the software.
  
  
• Providing the right types of program documentation boosts your brand by showing you're there for customers and employees.
  
  
• If you're the only one who understands your software, you'll probably be the only person who uses it. Where's the satisfaction in that?
  
  
• If someone else has to work on your code by updating or revising it, good documentation makes it a lot easier.
  

Good developers understand the types of documentation and their importance and that the importance and role varies from type to type.

• User manuals. This is the how-to software to which users turn when they're figuring things out. How do you configure the software? How do you convert a file? Can you add images? How do you fix a mistake? Even if the solution is a single click on the toolbar or the menu, there may be a lot of potential clicks through which to wade. Good user documentation makes it easier.
  
  
• Project documentation. Details of the project's development are valuable to your team as they work on it and possibly to users who want to customize an open-source program, for instance. The documentation can include contribution policies, best practices, change logs, product requirements, design guidelines and road maps.
  
  
• Requirements documentation. You'll usually draw this up at the start of the project. It defines the expectations for the software, including functional requirements, hardware requirements, compatibility and limitations.
  
  
• Architecture documentation. Defines the high-level architecture of the system: the components, their functions and the data and control flow.
  
  
• Technical documentation. Written for a technical audience, this covers the code, algorithms and interface.

You may be writing the documentation solo, but it's common to write it as a joint effort. Project documentation, for instance, may have contributions from project managers, engineers and designers. If you have a team working on the material, the simplest way to coordinate contributions is with an online template to which everyone can add.

There are five basic steps to creating user documentation:

1. Conducting user analysis to understand for whom you're writing the guide. For example, is your audience technically savvy, or is the guide for people who need much simpler, step-by-step instructions?
   
   
2. Drafting the documents.
   
   
3. Reviewing the documentation and gathering feedback.
   
   
4. Testing the usability of the documentation.
   
   
5. Editing based on feedback and testing. When you finish editing, you have a final draft.
   

There are several types of user documentation you may want to incorporate into your user guide to make it more helpful:

• Tutorial. This is a hands-on lesson giving an example of how to create a project. If your software is versatile enough to create multiple types of projects, you may want to include multiple tutorials. This is one of the best types of user documentation for people who have no experience with your software.
  
  
• A how-to guide. This feature tells users how to solve a real-world problem with step-by-step instructions. The target audience is slightly more experienced than the tutorial users.
  
  
• A reference guide. This is technical documentation covering the software's code and structure.
  
  
• Explanations. These can cover any added topics you think are worth discussing in depth. Pieces of the explanation are often scattered around in tutorials and other features.
  

If you're a one-person shop, you may have to write your own documentation. At larger firms, there's often a technical writing department that works with the software teams to develop documentation. Some firms prefer outsourcing the writing so employees can focus on writing code instead.

No matter the type of program documentation, you want it to be clear, readable and helpful. There are several things to keep in mind:

• Make it easy to find all the types of user documentation you've written. For example, you can turn the ReadMe file into the root node from which users can find and explore all the different levels of documentation.
  
  
• Update your documentation whenever you update your code.
  
  
• Watch for bugs. Test out the documentation thoroughly and try any code samples you include. If you find problems, fix them.
  
  
• Write well. You want documentation to be clear, understandable and easy to follow. Don't bog down your documents with technobabble and stiff writing. Even in technical writing, a human voice makes readers more comfortable.
  
  
• How well do you know your product? If the software is a team effort, work with the software until you're satisfied that you understand all the features. If you don't know the features, writing about how to use them will be difficult.
  
  
• The look of a document affects how easy it is to read. Long blocks of text with no indentations encourage eyes to look away. Break up text with paragraphs, diagrams and illustrations.
  
  
• Be concise. You don't want to skip over anything important, but readers will appreciate getting to the point swiftly.
  
  
• Add visual aids. Screenshots and video instructions are often better teaching tools than text.
  

In the internet era, you don't have to stop with a ReadMe file. You can also provide added types of program documentation on your website.

• If the website includes a blog, use that for added discussion of the software and what it can do.
  
  
• If you get questions from users, incorporate them into an online FAQ. This helps users and saves you time in dealing with individual queries. You can use the questions to shape updated versions of the user guide down the road.
  

Even if project managers don't write the documentation, they need to oversee it. Errors in documentation can lead to users making mistakes or to the finished documents not matching up with the vision of the stakeholders.

Some managers choose to draw up detailed documentation before forging ahead with the project. This can be effective if the product doesn't change much from conception to final form. If there are changes, however, the team will have to work to keep the documentation updated.

The alternative approach is to produce documentation just in time. Work on the software and then document what you've done when that's what you need to advance to the next stage. This has become the preferred approach because it prioritizes work on the software, and the documentation stays current if the project changes.