How to Create Quality Technical Documentation

Ahhh, technical documentation… The joys!

Everyone wants it for everything, but no one likes it. I know, I’m already losing you. Believe me, I’m right there with you. Who wants to read a post about something so, quite frankly, boring?

So exactly why is it so dull? After all, technical documentation helps us understand how a system, software, or service works. Understanding is useful. It all depends on how you present the information and how much attention the writer and the reader pay.

But there are also a whole bunch of tips and tricks you can use to take your documentation from something viewed as a last resort to documentation people can learn from.

Follow the advice in this post to make creating and reading the technical documentation for your next IT projects less painful.

What is Documentation?

Before we get stuck into solving our problem, let’s look at the definition of technical documentation.

Definition of Technical Documentation

Technical documentation, noun

1 Paperwork, papers Anglais paperwork, papers

2 Instructions, brochure Anglais documentation

3 Research Anglais research

I’m sure you’ll agree, it’s a bit vague! And that is precisely the problem.

The Problem with Documentation

THE most common instruction: “Oh, and don’t forget to document all that for me, right!”

OK… Document what exactly? And who for?

The person demanding the documentation is very rarely the intended recipient.

The Result: A Document with No Value

Without any specific guidelines, IT technical documentation quickly becomes a mountain of documents spawned at the start of a project that are soon obsolete and, therefore, of no use. Or they are created at the end of the project in a rush and are never updated.

This is why people often think documentation is expensive to write and difficult to read.

Now, Let’s Turn the Problem Around

How much time do you spend reading documentation before you start using new software?

What do you rely on when you start work on a project? The documentation or the code?

So, Is Technical Documentation Pointless?

No, of course not. But it is a matter of targeting: who is it aimed at? And what perspective do you approach it from?

What the Agile Manifesto Says:

“Working software before comprehensive documentation.” That doesn’t mean NO documentation. It just means it is less important than functional software. This does give us cause to rethink how we create documentation, however.

Which IT Technical Documentation Should You Choose?

Technical documentation is still useful and should fulfill a specific, identified purpose, that much is true. To make sure you create a document that won’t end up in the bin, you should choose the type of documentation best suited to your target audience.

Big Picture Documentation

This is pitched at everyone. As is often the case, it follows the “less is more” principle. It should sum up the scope of the project and its baseline in one simple sentence. If that is not the case, is your project scope adequately defined?

User Documentation

The only type you never skip. But be sure to use different media. Be creative! Choose documentation embedded in the software over a hard copy that will just gather dust on a shelf. Demos, videos, tutorials included in the software, etc. Put yourself in the user’s shoes. The faster they understand how your system, website, or application works, the quicker they will come to love it and use it time and time again.

Do you systematically read through hardware or software documentation before you get started? No, of course not. You should seriously consider user documentation at an early stage in the project, and linking this to usability considerations in general would be beneficial.

Some Examples of User Documentation

To highlight what makes for good user documentation and to give you some ideas, here are some excellent examples:

• Dropbox user documentation: The texts are short, the sections are well structured, and the breadcrumb trail helps users find what they are looking for quickly.

• SensCritique user documentation: It all fits on one page and it is structured in sections that roughly correspond to the site’s main “features.” The user simply clicks to find the solution to their problem.

• In-game tutorials in recent video games:

Project Tracking Documentation

Project tracking documentation is aimed at project managers and members. It may be produced throughout the project by project participants, as in Scrum Agile projects in particular, by using simple, appropriate hardware or software tools.

This means project tracking documentation is created in real time and with minimum effort.

Technical Documentation for Developers

As its name suggests, this type of documentation is aimed at developers, and only developers. These developers may be involved in the project, but they may also be external, for example, when providing web services or a framework.

Two different scenarios are possible:

• Architecture documentation: This comprises a set of charts, diagrams, and lists
• Comprehensive documentation: Can be generated automatically

The purpose of technical documentation is to speed up the development of new features. The developer needs to be satisfied with and trust what they are reading. It should be systematically up to date and clear. No hassle, no fuss. The answer should be quick to find.

Automatic Generation of Technical Documentation

As we’ve seen, technical documentation is not something to be taken lightly. Even though it can be restrictive, there are tools you can use and tips you can follow to automatically generate the IT documentation for your system or solution.

How Do You Ensure Quality Documentation?

• It should be synchronous with the code
• It should be written at the same time as the code
• It must be readable from inside and outside the code: This is called multicasting

Here are some public examples: Javadoc, MSDN, phpDocumentor, Amazon EC2 API Reference.

Ultimately, the only excellent documentation is written into the code directly. That is the only way to meet all the requirements.

Using C# Documentation Tags and Extracting XML Files

To simplify the code, you can use the following tags to identify your lines:

• <summary>: the summary
• <param>: parameter details
• <returns>: returned object details
• <exception>: returned exceptions
• <code>: code portion
• <example>: example of use

You will find all the existing tags in the Microsoft recommended tags in C# documentation.

When compiling the solution, you can request the generation of any raw documentation data. This configuration should be adopted for all of a solution’s projects. Here are the steps to follow in the Visual Studio IDE:

• Visual Studio 2013/2015: Project Properties > Build > Output > Check the “XML documentation file” checkbox and enter the XML file path

• Visual Studio 2022: Project Properties > Build > Output > Check the “Generate a file containing API documentation” checkbox and enter the XML file path

Coding, Extracting, and Distributing Technical Documentation

Here are some solutions to help you generate documentation for our .NET projects:

• GhostDoc: A handy tool to help you with C# documentation input.
• Sandcastle Help File Builder (SHFB): This Sandcastle add-on lets you extract and display documentation in various formats (CHM, HTML, XML, etc.) from the XML files created in the last step. This is how Microsoft provides its documentation automatically. To find out more, here is the GitHub page for SHFB.

Executable Documentation and Documentation for APIs

Requirements and functional tests can be included in the same tool, for example, FitNesse.NET or GreenPepper. These tools let you code requirements testing in natural language. With a few conventions, you can code user scenarios of the type “as X, I can perform operation Y to achieve result Z” easily. This produces executable documentation (or an executable specification).

In addition to documentation for a heavy web client, you can also generate documentation for APIs using the Swagger solution. If you are interested in finding out more, our “How to Technically Implement an API” post(only available in French) looks at how this tool works and how to use it.

Technical Documentation: Mastering the Reference Document

Authoring technical documentation worthy of the name is far from easy, but it is essential for your project, solution, application, or system, especially if it is designed to be accessed by other people!

The best way to achieve this properly is to think about your target audience and the different questions they may have when using the tool in front of them. So, before you start drafting this reference document, think about choosing the right type of technical documentation or use automatic generation if you need to create technical documentation for developers.