Community mailing list archives

Re: Reflection about documentation.

Elico Corporation, Eric Caudal
- 08/12/2014 08:47:17
Actually we have had  last night during the OCA board meeting a discussion about this topic and the OCA wants to start a specific project in order organize the functional documentation for the projects hosted under OCA umbrella.
Concerning Odoo standard documentation, I recommend to contribute directly to Odoo (with how-tos, help center etc.) and probably Olivier Dony.

For OCA modules, I see 3 main area where this topic could be improved:
- Contextual information: better and systematic help for all fields, contextual help for form views.
- Improved functional description of the module with how-tos and use cases.
- External documentation (resource center): videos, ppt, pdf etc.
I personally think that embedded documentation (in html description or field help) is more effective and up to date than external resources but additional well organized resources are always a good thing (reachable all from a centralized point).

Here are some areas where we would accept like to accept contributions:
- Define the reasonable tools accepted by everybody.
- Criteria for a certain level of functional documentation ("what is acceptable") to have a module accepted in OCA.
- Some of those criteria will be subjective (quality of the content for the example)
- Some criteria are very simple to set up. eg: all field must have contextual help, all module description must contain one use case.
- A  reviewers committee should validate the functional documentation in a similar process currently followed by technical review and pull requests.
- Some experts pools should work on naming and conventions in certain expertise area (to ensure consistency and avoid regional "faux-amis").

We will create a project "Functional Documentation" under OCA for this topic and I will lead a first round of discussions and gather ideas and contributions.
Based on feedback and contributors, we will propose a first blueprint to the community to submit for approval.

Looking forward to reading you

Eric Caudal
OCA Board Member

On 08/12/2014 08:04 PM, Kurt Haselwimmer wrote:
<blockquote cite="" type="cite">I agree - the documentation gives a very poor marketing impression. If odoo's claim that they do not wish to lock their customers in is to be taken seriously the documentation needs to be coherent, systematic and transparently available. 

Odoo SA and the community cannot rely upon answers to questions at - for example 7 out of the 8 questions I have posted since mid June remain unanswered - even though they are not complex technical questions (eg where can we post feature requests, are there product feeds for google merchant, etc)

Kurt Haselwimmer

Dr. Kurt Haselwimmer

Hertford Developments Ltd
Willow House, 100 High Street, Somersham, PE28 3EH
Tel +44 (0) 845 899 0257  Fax +44 (0) 845 899 0259

Good afternoon,

I would like to make a constructive reflection on what for me is one of the most obvious areas of improvement: documentation.

After browsing various websites, I could find ppt presentations, youtube videos, books, and even some functional and technical documentation on the website of odoo. All this is fine, but from my point of view always starts from the top and there is never time to lay the foundation. For a final version is released and must be accompanied by a full technical and functional documentation. The purpose of this documentation should be able to aspire to any user, customer, partner, etc. you can refer to find any questions related to the technical performance or functional official modules (and this today has not been achieved with any version of OpenERP or Odoo).

The image odoo with customers who consult the documentation is very negative (incomplete documentation, links to nonexistent pages or different versions of documentation, outdated information and so on). The videos, ppts, books, help/forum, etc. are added value contents to promote odoo, but can not be the basis on which the knowledge is built for users, customers, partners and community.


The learning curve with this documentation is very slow for users and technicians and because the software is completely friendly don’t becomes even slower.

I invite everyone to reflect on this issue to try to find a solution because the final product and the documentation are in different levels.


Best regards.


Post to:

Post to: