What must the software documentation contain

Superior software documentation

- Brings the functions of your software to light -
- Outshines competitors -
Software documentation in the broadest sense sometimes includes very different areas. This often leads to misunderstandings.


Subdivision according to the use of the software documentation



Software documentation can be roughly divided into types of documentation for internal use by the manufacturer and types of documentation to be passed on to customers.


For internal use, the software documentation includes in particular:

▶ internal Project documentation

▶  Documentation in the source code


For external use, i.e. for passing on to customers, the software documentation includes in particular:

▶  User documentation

▶  Interface documentation (API documentation)


Subdivision according to the type of information

the software documentation

Typically, user documentation contains at least three fundamentally different types of information:

▶  Basic knowledge on the general concepts behind the software and, if necessary, additional specialist knowledge (domain knowledge) that the target group is still lacking

▶ gradually Instructions for use

▶  Reference information for reference, e.g. B. on individual parameters


Mixing these types of information rarely makes sense, because they are almost never needed at the same time at very different points in time. Often these types of information are even divided into different documents or parts of documentation, e.g. B. in a "User Manual" and in a "Reference Manual".


Subdivision according to the medium

the software documentation



In addition to the content level, there are also fundamentally different types of software documentation in terms of the medium:

▶ printed or printable Manuals with a fixed page sequence (including PDF)

▶  Online documentation (Online help) as real hypertext, mostly HTML

Software documentation should be part of a holistic software user assistance



Software documentation for users should ideally always be in a global context: the context of holistic software user assistance. These are all measures that assist users in their use of the software. In addition to the classic documentation, consisting of manuals and online help, holistic user assistance also includes:

▶ small, already Info texts integrated in the user interface

▶  Screencasts (Software videos)

▶ interactive Tutorials

▶  Sample projects

▶  User forums and communities

basic requirements


The most important and at the same time the most frequently neglected requirement for software documentation is: Software documentation must answer customers' questions and enable them to use the product fully and efficiently. Not more! It's not about what we want to say in the software documentation, it's all about what the reader wants to know. Technical details, which we are rightly proud of, but which readers don't need to know, have just as little lost in software documentation as grandiose phrases and "buzzwords" from the marketing department.

The art of creating software documentation is to use the software documentation to close the knowledge gap between what the reader already knows and what he does not yet know but needs to know. Less information is too little, more information is too much.

Let's not kid ourselves: Nobody reads documentation for fun. Technical documentation, and thus also software documentation, is usually only perceived as an annoying evil. It is only read when the pain of not being able to use a function is greater than the pain of having to read the documentation. When creating software documentation, the aim is always to keep the pain of reading as low as possible.

The pain is minor if:

▶ the information can be found quickly and without detours

▶ Exactly the right information is found, i.e. nothing irrelevant has to be read

▶ the information is easy to understand, i.e. as little thought has to be done as possible

▶ the information can be applied to one's own problem and can be understood in a practical way

▶ reading is fast


Legal and contractual requirements



In contrast to other forms of technical documentation, there are hardly any legal requirements for software documentation or requirements resulting from certain standards. In most cases, the only general requirement for documentation is that it must enable customers to use the product fully and successfully.

In addition, special requirements may arise based on contractual agreements with customers or from specially assured properties. If, for example, it is advertised that software has a special interface, then this interface must also be documented in such a way that customers can use it successfully.

If software controls machines or devices, the relevant standards for these machines and devices can also be relevant for the software documentation. This applies in particular to the design of warning notices.

Developer or technical writer?



The creation of software documentation is often perceived by developers as an annoying evil and is not necessarily one of the tasks that everyone rages on. And yet: A large part of all software documentation is written by the software developers themselves. In addition to the personal lack of motivation, writing by developers has the main disadvantage that the developers themselves are far too deep into the matter to be able to provide an outsider with the information they need in a generally understandable form. This is especially true for user documentation. Anyone who programs software themselves automatically has a completely different view of the product than a user. Adopting the user perspective is an essential requirement when writing user documentation if the documentation is to be really good and to reflect the questions of the users. As a developer, breaking away from the primarily technical point of view is incredibly difficult and only succeeds in the rarest of cases.

To be able to professionally create technical documentation, and thus also software documentation, requires special training and a certain talent. Today there are independent, multi-year courses for this purpose. Everyone can write, but not everyone can write automatically in a way that everyone understands!

On the other hand, developers have the great advantage of being right at the source of the information and therefore being able (at least in theory) to describe things that an author who is not directly involved in the development might miss.


Conclusion


As a know-how supplier, developers are irreplaceable. In general, it can be said: The closer a documentation is "to the code", the more likely it should be written by developers themselves - e. B. an API reference. The more a documentation has to cater to the users of the software, the sooner the documentation should NOT be designed and written by developers, but by an experienced technical writer.

A combined workflow for creating software documentation can also be particularly efficient: Developers and know-how carriers compile the important facts and write an initial rough version of the documentation. You concentrate exclusively on the content and do not "waste" time on formulating and formatting nicely. In a second step, an experienced technical writer prepares the content in such a way that software documentation that is also understandable for customers is created. This model is particularly efficient because everyone does exactly what they do best.
If a high-quality, professional software documentation is to be created, you cannot expect that a developer without the appropriate training will shake this documentation off the sleeve.

If you cannot hire a technical writer and do not want to hire a service provider who specializes in the creation of software documentation, there is only one solution left: You must impart the necessary basic knowledge to the employees entrusted with the creation of documentation so that these employees can create understandable, user-friendly documentation.

You can achieve significant improvements surprisingly quickly. As in many areas, the well-known 80:20 rule (Pareto principle) also applies to technical documentation: 80 percent of a possible increase in quality can be achieved with 20 percent of the funds. There are already worlds between a haphazardly created software documentation and the 80 percent level!

The key areas for which you should know the top best practices are:
Best Practices for Structure
of software documentation

Which documents should you create anyway? Printed or online or both? How do you structure these documents? How do you lead the reader quickly and successfully to the content that is relevant for exactly this reader?
Best Practices for Shape of software documentation

How do you design your documents so that they not only look good, but also make it easy for readers to take in and keep track of the information?
Best Practices for Write of software documentation

How do you write simply and clearly so that readers understand the information as easily as possible? The content is usually complex enough, so at least the language should be simple!
My name is Marc Achtelig. I have been creating software documentation full-time for more than 25 years.

As a consultant for software documentation and a freelance technical writer, I offer you the following services, among others:

▶ Optimizing existing documentation

▶ Designing new documentation

▶ Writing of manuals and online help

▶ Creation of format templates for manuals and online help

▶ Advice on the selection of editorial systems

▶ Training


If you are interested, you can find more detailed information about my services on my main website www.indoition.com.

I am happy to help you personally. You can find my contact details below. I'm looking forward to hearing from you!


your
Marc eighth