Albert Cervera i Areny Aug 27, 2010
<div>We will probably agree that documentation is one of the main issues in most open source projects and OpenERP is no exception. Fortunately, this rule is not always true. Some projects such as <a href="http://www.postgresql.org/docs/8.4/static/">PostgreSQL have excellent documentation</a>, so there is still hope for OpenERP users and new developers.</div><div> </div>
<div>At <a href="/en">NaN</a> we analyzed the problems users, developers, documentation writers and translators face with documentation and we tried to solve them with a new 'documentation' module that we have just released. It integrates with our Koo client, but we hope the rest of the clients and module writers, specially OpenERP, sa will join the effort. So yes, we think we were able to solve most concerns and now we have a powerful yet easy to use framework waiting for new contributors.</div><div> </div><div>In this post I will explain you what are the requirements we detected for each of those groups of users and contributors and in another post I will expose the solution we gave to each of them.</div><div> </div><div> </div><div><span class="Apple-style-span" style="font-size: large;">Users</span></div><div> </div><div>Users usually need two kinds of documentation. In one hand they want a book that can be read without the need of having the application opened. Something that can be read to have a general idea of the application and how things work and interact in the application. On the other hand, they want help when they need it (ie. when they're working). So they need an icon they can click and get contextual help while introducing information in a document such as an invoice, for example. In both cases, they will want screenshots to help them understand how things will look like and (specially important) in what menu entries they will find what they're reading.</div><div> </div><div>At the same time users will hate it if they need to know what modules they have in the system. One of the main problems with current documentation is that OpenERP cannot have a single book that explains how the ERP works. That simply has no sense because OpenERP is highly extensible and behavior can vary depending on what modules you have installed. Traditionally, applications have solved this with a large list of "if's" that make the documentation unusable, something like "if you have module X installed you will get XX behavior, if you have module Y installed you will get YY behavior, if you have...". So it is important to keep this in mind: You cannot have a document with the documentation of OpenERP unless you know what modules are installed.</div><div> </div><div> </div><div><span class="Apple-style-span" style="font-size: large;">Developers</span></div><div> </div><div>Developers hate documentation and that's a fact. That said, the hate can be somewhat minimized if we know the reasons of their feeling.</div><div> </div><div>One of the concerns is that users never read documentation, and there is probably some truth in this statement, many users will not read the whole OpenERP book, but it is also true that they will use the help provided in fields, for example, and that is documentation too. That is what we call contextual help or <i>the help when they need it</i>.</div><div> </div><div>Another concern is that writing documentation somehow <i>breaks</i> the programming process. If you do not believe it, think of OpenERP modules. In many cases, the developer didn't write documentation explaining what the module does but he/she actually used the 'help' hint in several key fields. So there seems there is some truth in this statement and thus, keeping documentation in another repository and unlinked with module versions and changes does not help either.</div><div> </div><div>Another important aspect for developers is what tools are used for writing the documentation. A system that is friendly with the console and simple text editors is probably a must.</div><div> </div><div>It is also worth noting that the few projects that have excellent documentation even though they do not have a lot of manpower, such as PostgreSQL, have strict rules regarding documentation writing and no patches are accepted without the appropriate docs. To keep track of this, documentation is stored in the same repository and committed with source code.</div><div> </div><div> </div><div><span class="Apple-style-span" style="font-size: large;">Documentation writers</span></div><div> </div><div>In many cases, developers will be the documentation writers, but in this section we will treat aspects that are not necessarily geek ;-)</div><div> </div><div>Some of the issues of documentation writers include:</div><div><ul><li>In the case when the documentation writer is not the developer that created the module, they will need a way to easily indicate that the documentation they're writing is linked with the given module without the need of modifying the module itself. Even if the documentation should ideally be linked with the code in the same module, they need a way to make documentation for modules over which they do not have control (ie. commit rights).</li><li>When documentation writers are not developers they will need a system that is usable by non-geeks.</li><li>Creating screenshots is one of the worst issues to keep documentation up to date. If we add the fact that views vary depending on the modules installed and even on a per user basis (some users may have some fields that others don't) it seems to be almost impossible to have useful screenshots without a huge effort.</li><li>It is complicated to keep up to date field names and menu entries in the documentation if they're changed by developers in the source code, so they need help here too.</li></ul></div><div> </div><div> </div><div><span class="Apple-style-span" style="font-size: large;">Translators</span></div><div> </div><div>Translators suffer similar problems to those of documentation writers. Mainly:</div><div> </div><div><ul><li>Keeping screenshots up to date. Yes, even if documentation writers were be able to create screenshots for all the cases we mentioned, translators would have to create them again for their own language.</li><li>Using the exact same words for menu entries and field names that were used for translating the fields and menu entries that users see in the application.</li><li>They need a translation system that lets them easily keep track of what was translated and what not. Doing a translation as if it was a single book that never evolves seems to be calling for problems in the near future for translators.</li></ul></div>
