Community mailing list archives

Re: Reflection about documentation.

Vauxoo S.A. de C.V., Nhomar Hernandez
- 08/12/2014 10:46:04

On Tue, Aug 12, 2014 at 9:05 AM, Miguel Acebes <> wrote:

The problem now is not of translation into multiple languages, the problem is that there is no documentation of quality in English. Then you might consider translating it into other languages.
Regarding Oca, I think it is more critical to document the core of Odoo (official modules) first, let's start with the foundation of the house.

Hello Everybody.

Even if you are partially right ( I strongly think you don't know all sources of information), it is a matter of people on community, documentation has been able to be improved freely since 6 years ago, but the issue is that not to much people take this reaponsability by themselves (neither Odoo and neither somebody in community), we afford the job of translate to spanish in order to sale the book 3 years ago and it was a Huge amount of work and when it was ready simply it was outofdate.

IMHO - It is a matter of co-responsability, @Miguel if you think your customers need more documentation, develop these documentations and make a PR to the project or a MP in launchpad "Everything in sphinx" if you decide document locally with other tool you will not be able to be co-responsable for it [1].

IOH, I think Odoo is basing everything in the "usability approach", it means all documentation is not necessary because it is "obvious to use", and I think (it is not totally wrong, not totally right), we need process, we need how-tos. we need user cases, but the fact that majority think: "If it is from the core, then it is NOT my responsability", and "If I learn in the hard way it is too expensive for me put it freeley availabe". (Including Odoo) then the documentation becomes slowly improved.

Other thing to considere is that with the OCA we will document generally at least improvements not the core, but it is necessary too.

Don't forget the new documentation process (i really preferred sphinx but it is a taken decision), then in the mean time we are coding and hacking "Who propose documentations¿?¿?¿".) [2]

With the SaaS offer becoming the main objective, all the documentation, will be related to it, always on saas-x (Who take the responsibility of document the stable on-premise version?).

As you can see it is a really difficult approach, being inmerse in Odoo world it is a little different from other tools, if you don't at least read the code, it will be complex to "guess" obvious things, and what looks "obvious" may be was not considered, it doesn't become odoo in a "good" or "bad" system, it is just a matter of fact.

My 4 Cents just to conclude:

1.- Odoo should be based its theory behind in the "correct" theory (Universities, process already documented and so on) please stop to re-invent the "WMS" process.... just re-use concepts it is too easy, and "link this information" to the system thats all (that for conceptual part).

2. Community, if you learn something propose a doc, fork and improve it, in the central places, stop fork and spread the knowledge let's build a central place to achieve that.

3.- Customers, learn to make public questions "That enrich the ecnosystem too", and if you learn something cool, document too!.

4.- Partners (majority the new ones) stop to make blog posts with the unique intention of make marketing by your self only, enrich the web too!.

5.- Odoo, continue making this kind of blog-posts [3], but you need to give them more presence, use more the lists to spread the word.

6.- We need more "formal and structured documentation" like the books Let's write more and more (for that it must become a profitable business model "buy more books when they comes out".

7.- Odoo please estabilice the concepts, we can not have strong workflow of documentation with this kind of eternal inertial rodes you are having, Remember any energy is eternal ;-).