Community mailing list archives
Re: Reflection about documentation.by
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
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.