Community mailing list archives

RE: Reflection about documentation.

Miguel Acebes
- 08/13/2014 17:47:49

Good night all,

I’ve just opened the mail and I'm pleasantly surprised of the interest that the issue of documentation is raising.

First of all I want to thank Fabien Pinckaers for his kind answer, especially for the transparency and humility with which he has treated the subject identifying the efforts that have been made by Oddo and the improvements areas.

In this sense and using the heat of the moment and the availability I see in the community, I want to propose you to take the bull by the horns (as we say in Spain) and start the way to help seriously and professionally to OpenERP SA from the community.

I’m a manager who comes from the world of telecommunications and consulting multinationals so I cannot provide too much from the technical point of view (despite being a Telecommunication Engineer) but I can humbly contribute to lead, manage, coordinate and establish mechanisms to try to make a success of this documentation project.

I propose to establish working groups with clear and specific areas of responsibility with the participation of the community and Oddo.

These could be the working groups and a possible draft of responsibilities.

Please I would like to know your opinion, and feel free to introduce any change you consider necessary to improve my proposal.

Thank you all.


Working Groups


1.           Executive Committee

a.           Setting objectives, priorities and quick wins

b.           Project Planning and Tracking

c.            Reporting (dashboards) to the working groups, community and Editor

2.           Marketing and Documentation Working Group

a.           Define the strategy

b.           Documentation format (typography, styles, pictures, logos, colors, etc..)

c.            Types of docs, how to do, pdf, presentations, videos, etc.

d.           Types of documentation regarding the different kinds of receivers (tutorials, quick guides, Odoo Bible, etc.)

3.           Quality Working Group

a.           Definition of writing styles

b.           Drafting of regulations to use

c.            Define a quality system for the document management

d.           Track regulatory compliance and the quality control

4.           Contents Working Group

a.           Defining the content to be included in the different phases

b.           Scope of content for users, developers, designers, consultants, partners, etc.

c.            Writing contents

5.           Front Working Group

a.           Find and propose an appropriate platform to make available to all final documentation

b.           Implement the platform

c.            Trading Platform

d.           Maintaining the platform

6.           Back Working Group

a.           Find and propose an appropriate platform to work on contents

b.           Implement the platform

c.            Trading Platform

d.           Maintaining the platform

7.           Translation Working Group

a.           Define priorities of languages

b.           Translate into different languages documentation

c.            Keep updated translations


Best regards,


Miguel Acebes

De: Fabien Pinckaers []
Enviado el: miércoles, 13 de agosto de 2014 18:08
Para: Community
Asunto: Re: Reflection about documentation.


Hi everyone,


It's clear that documentation is a key topic to onboard new users,

developers and designer.


Despite huge and continuous investments on building and adapting

documentations, we always struggled to get something great. Lots of

books have been written, content has been adapted to every new version,

lots of different documents / platforms, ...


We mostly failed in:

- focusing everyone to work on the same direction rather than having

  every contributor that do stuff in his own way.

- getting the right tool/platform; loved by contributors, clear for

  reader, accessible for developers


The challenges are not the same according to the type of doc:


We have 2 issues with the functional doc:

1/ Odoo is evolving very quickly. Something that should be explained

   in a version will be improved in a future version. It's like

   building on quicksand; every year you have to rewrite a large part

   of the doc.

2/ The documentation to cover is huge, because Odoo is huge. You can

   write around 1000 pages (current size of the doc) and it will not

   answer 50% of user's questions.


For technical and designer doc, we don't have such issues. The framework

do not change too much year over year.


Our priorities



The designer and developer documentation is a key priority. We started

to rewrite all the documentation to adapt it to v8. You can follow the

work in progress in this branch: 8.0-newnewdoc-xmo


We plan to write, for developers:

  1/ A tutorial

  2/ A reference guide

  3/ An API guide


For designers:

  4/ A designer tutorial


We expect to release at least 1/, 4/ and partially 2/ within around 4 weeks.



For the functional doc, we decided we will put most of our focus on

making the software easier through improved usability, on boarding tips

and configuration/deployment tools for every app. Example with this

mockup: (click on the top green zone)


In other words, we will invest time so that users do not need a

documentation any more. (a status we will never reach but will tend too)

I think the pay off will be better if we put 500 man*days on usability

tools rather than 500 man*days in writing documentation or a balance

like 400 man*days tools+100 man*days documentation.


So, functional documentation is not our priority and we know we will not

be able to create a complete documentation by our own. But we would be

very happy to help the community succeed in building something if you

are ready to seriously contribute.


So, the only way to build a great documentation is to have:

  1/ a lot of contributions (like on

  2/ with a good coordination / leadership to align everyone on the

     same direction.


We can help for 2/ and a bit of 1/. But we will succeed on 1/ only if we

succeed to create a strong translator group.



To help you measure the effort we put in the documentation, some numbers:

  - Sources v7 (.py): 858.000 words

  - Doc v7 :          209.000 words


And these 200k words have to be reviewed every year, at every new

version. This is why we really have to choose our priorities. It's a

super big task.



Moving forward



For the functional doc, we tried to build how-tos based on the Q&A

platform. Here is what have been written after 30 man*days by

experienced people:


With the feedback of this approach, I am still not convinced it's the

way to go. A traditional Sphinx + clean CSS + github would do the job




We would like to have the documentation on, not on a separate

website. So, we will use the sphinx template of XMO (one based on the

bootstrap documentation). We implemented a clean CSS rendering and we

can connect it to transifex through github (though I think translation

is not the priority, to not spread efforts too much)


I prefer the bootstrap template over Readthedoc because of the Afix

module that keep it available so that you don't always have to scroll to

the top to navigate the ToC.



So, next steps:


1/ We will finish our technical doc and communicate on it as soon as

   it's ready to be published


2/ We created the "Community Translators" mailing list to start

   organising discussions and responsabilities amongst translators


      Join here:

      Write to:


3/ We will move our efforts on the technical doc to a separate

   repository with public write access. We initially put it in a

   odoo/odoo branch fork. But, for access rights, it's better to have

   all docs in a separate repository.


4/ Can someone contribute to restructure the existing documentation

   into a new and clean structure? If someone is ready to do this

   (around 20 hours of work), we can discuss together on how to do it.


5/ Once we will have the structure of the documentation, we will be

   able to assign responsibilities on writing / improving chapters.


6/ We will clean the platform and add missing features from readthedoc

   but we will keep the design of bootstrap. (the only things we

   need is to connect transifex to the github repo and the Edit in

   Github button)



The focus for the new documentation should be on a tutorial approach (to

help new users configure/deploy/use) and not a reference guide that

answers all questions (it's just too big).




Side note



I read in the thread that some people think having a bad documentation

was a strategy to sell services. (revenue model) To be clear: it's not

our business model and we think it's a stupid approach. Our approach is

to build an exceptional product and help to on board new users (through

better UI, docs, ...) We never had plans to sell docs or support services.


We sell Odoo Enterprise: upgrade to benefit from new features, bugfix

guarantee and optional hosting. We also sell trainings, but it's not key

to our business model. We sell trainings because people need them

(requirement to have new partners/users) but scalability of trainings

are such that it's not good enough to sustain our R&D efforts.


We have plans to sell support contracts but I am convinced that the

better the documentation is, the more support contract we will sell.

(because Odoo will have more users with a better doc)





Fabien Pinckaers

Odoo Founder


Phone: +


Twitter: @fpodoo


Instant Demo:

Post to: