Reviewed Documentation Process

The documentation of OpenERP is one of our biggest priorities. We currently have the best documentation amongst all open source ERP but it's not enough and I am sure we can do much more better.

We already invested a lot in writing documentation and the result is not as good as we were expected: the software is growing very quickly and writers have lots of difficulties to track changes and write quality documents.

Writing a Good Documentation is Complex


For Years, we have try to make a community based documentation on a wiki where everyone contribute. With OpenERP, we have a strong community but, after years, the community documentation does not reaches our expectations:

• Deprecated compared to new versions of the software,
• Original authors do no maintains what they write / contribute,
• Seems like if we assembled different pieces of unrelated documentations,
• Sometimes contributions comes from people that do not understand perfectly the software,
• Not end-user oriented,
• Some wants to write in English, others in French, Spanish, eso.
• Some have experience only in food industries, others services companies, others manufacturing, eso.

We also tried to make documentations written by our own developpers. The idea was that each time a developer finish a module, he writes the documentation about it in the wiki. It did not work too because:

• Developers have lots of priorities and sometimes a hurry customer is more important than writting the documentation in the wiki,
• Writting a good documentation on a part of the software can easily take 100 hours, most of the developers do not have such a time,
• Some developers do not like to write documentation so the work does not reaches a very high level of quality,
• Most of the time, a developer develop a module for one customer only, so the documentation will be oriented based on one case only.
• A good documentation has to be written by functionnal people that have a strong experience on how they use a particular module in production,

Having said that, we decided to review the way we will write and maintain futur documentations about OpenERP and OpenObject.

The New Process

I had a look at the open source software with the best documentations. Most of these documentations have been fully written in one try by only one or two people / author. After that, the community improved the content with small improvements from here to there.

So I think we'd better have to focus our ressources on some good individuals rather than a global community. But writting a complete documentation (or a complete chapter) can take a long time (we took about 200 hours to write the OpenERP book in french, 280 pages). So we need incentives as to motivate these contributors / authors.

So, we decided to manage all documentations about OpenERP through real books. We will setup a real editing chain with the following actors:

• The editors: will work with authors to review the quality of the book and will distribute in a range of countries through webshops and real bookstores. The editor also define authors contracts and the graphical charts and style. He will manage the collections (set of books).
• The authors: everyone can write his own chapter(s) and propose them to the editor. The editor will make a selection of chapters to publish complete books.
• Re-Readers: will re-read books before publication and work with the editor to achieve a high level of quality.
• Translators: will translate a particular book to their mother tongue based on the english version.
  

Editors will be different according to the coutries. For all french countries, we already contracted our preceeding books with Eyrolles. For the english version, we will create our own edition company as to keep the rights on the text to be able to publish it online for free.

Now, we have our incentives for authors and translators:

• Getting a monthly revenue through author rights based on monthly sales,
• Being published in bookstores with our worldwide distribution channel.

Having established that, this should leverage individuals effort and promote contributions on writing good documentation. As people will be published and paid for their good work, this should promote new authors and translators.

Books are sold in bookstores in different countries and languages, this allow us to remunerate the full edition chain through author rights. It will help us to motivate authors and translators to write more chapters, and improve existing ones.

We had to find a good middle point between selling through bookstores to remunerate authors and publishing online to provide a free version. So, most of our books (depending on the contract we have with the editor in the related country), will be published online some months after their official publication.

Our goal is to create lots of different books for different domains: technical books, marketing management, services companies management, openerp for accountants, ...

Books writing will be our main documentation process. At each new version of OpenERP, we will release new versions of the different books. The editor will organise this and will get revenues for this.

In addition to this, we use a community wiki for all others documentations that are not directly related to the software or for documentations that are "per module". For our main knowledge management system, we use Launchpad Answers, where you can ask questions or reply answers.

Current Status

Lots of things have to be set up to be efficient in this editing chain. As a proof of concept, we wrote the first book with Eyrolles: OpenERP, pour une gestion d'entreprise efficace et intégrée. It was a great success, they expected to sell their printed stock in 18 months and they had to reprint after only 2 months !

This book is already translated to english and some chapters are being added. We plan to release it within maximum 2 months, at the same time of the next OpenERP major version (5.0). We also find translators to translate it in 6 others languages. We are looking for editors in countries we don't have a distribution chanel yet.

Some others books have started being written or are in the pipeline:

• OpenObject: build or customize application quickly, without developments
• Office Productivity: Business Intelligence, Document Management System, Email Integration, Word/Excel plugins, ...
• Pre-Sales & Marketing: based on our new CRM and direct marketing modules

These very firsts books allowed us to setup the rules for clean and systematic processes: defining stylesheet and guidelines, reviewing process, role of the editor, contracts for author rights, findind printing and distribution channels, ...

So the next phases are:

1. Release the english book
2. Create the edition company and hire people within it
3. Define all the processes in details
4. Translate the english book and contracts with authors/translators
5. Work on futur books

The Role of The Community

This documentation writing and maintaining process tends to emphatize individuals efforts from authors and translators. This does not means we think the community is less important for writting documentations. The community remains very important for different reasons:

• The community provides authors and translators because everyone can request to be an author for one or several chapters, no need to write a full book.
• The editor needs readers that will review the book before his official release.
• These readers will be choosed amongst the different contributors in the community.

To improve the quality of books versions after versions, we will extensively work on erratas in the wiki. Community will be able to propose improvement through the errata section.

You can get detailed information about the process in the wiki.

Contact

Contact me if you are interested to contribute in one of these aspects: being an author, being a translator, setting an edition company, ...