Documentation needs of users and contributors

Probably we will agree that documentation is one of the main problems of most open source projects, and OpenERP is no exception. Fortunately, this rule is not always true. Some projects, such as PostgreSQL, have excellent documentation, so there is still hope for users and new OpenERP developers.

At NaN we analyzed the problems that users, developers, documentation writers and translators encounter with documentation, and tried to solve them with a new documentation module that we have just published. It integrates with our Koo client, but we hope that the other clients and module developers, especially OpenERP, will join the effort. Therefore, we believe that we have solved most concerns and now have a powerful and easy-to-use environment, awaiting new contributors.

In this article I will explain the requirements we identified for each of these groups of users and contributors, and in another article I will present the solution we provided for each of them.

Users

Users generally need two types of documentation. On the one hand, they want a book that can be read without having the application open. A document that can be read to get an overview of the application and how things work and interact. On the other hand, they want help when they need it, while they are working. Therefore, they need an icon they can press to obtain contextual help while entering information in a document such as an invoice. In both cases, they will want screenshots to help them understand what things will look like and, above all, which menu entries contain what they are reading.

At the same time, users will hate having to know which modules are installed in the system. One of the main problems with current documentation is that OpenERP cannot have a single book explaining how the ERP works. This simply makes no sense, because OpenERP is highly extensible and its behavior may vary depending on the installed modules. Traditionally, applications have addressed this with a long list of “ifs”, making the documentation unusable: “if module X is installed, you will get behavior XX; if module Y is installed, you will get behavior YY; if you have...”. Therefore, it is important to keep this in mind: you cannot have a document with OpenERP documentation without knowing which modules are installed.

Developers

Developers hate documentation, and that is a fact. That said, this aversion can be reduced if we understand the reasons behind it.

One concern is that users never read the documentation, and there is probably some truth in that statement. Many users will not read the entire OpenERP book, but they will use the help provided for fields, for example, and that is also documentation. This is what we call contextual help, or help when they need it.

Another concern is that writing documentation somehow “breaks” the programming process. In many cases, developers did not write documentation explaining what a module does, but they did use help text on several key fields. It therefore seems that this concern has some basis, and keeping documentation in a separate repository, unlinked from module versions and changes, does not help either.

Another important aspect for developers is the tools used to write documentation. It is probably essential to have a system compatible with the console and simple text editors.

It should also be noted that the few projects with excellent documentation despite limited human resources, such as PostgreSQL, have strict documentation-writing rules and do not accept a patch without the corresponding documentation. To track it, documentation is stored in the same repository and published together with the source code.

Documentation writers

In many cases, developers will be the documentation writers, but in this section we will discuss aspects that are not necessarily technical ;-)

Some problems faced by documentation writers are:

• If the documentation writer is not the developer who created the module, they need a way to easily indicate that the documentation is linked to the corresponding module without modifying it. Although ideally documentation should be linked to the module’s code, they also need to document modules they do not control and for which they lack publishing permissions.
• When documentation writers are not developers, they need a system that non-technical people can use.
• Creating screenshots is one of the worst problems in keeping documentation up to date. Since views vary depending on installed modules and even by user, it seems almost impossible to have useful screenshots without enormous effort.
• It is difficult to keep field names and menu entries up to date in documentation when developers change them in the source code, so writers also need help with this aspect.

Translators

Translators face problems similar to those of documentation writers, mainly:

• Keeping screenshots up to date. Even if documentation writers could create screenshots for all the cases mentioned, translators would have to recreate them for their own language.
• Using exactly the same words for menu entries and field names as those used in the translated fields and menu entries users see in the application.
• They need a translation system that allows them to easily track what has been translated and what has not. Treating a translation as a single book that does not evolve is looking for problems in the translators’ immediate future.