Community mailing list archives
RE: Reflection about documentation.by
@Nhomar have not understood any of my mail. Who released the new versions is OpenERP SA and not the community and should be responsible for making a great documentation. If that means we will all need help there to help. But they have to understand that they can not release the modules undocumented. What means an saas client that can make a website without documentation?
Odoo must include documentation of the project as part of a new version or module. I'm not inventing the wheel gentlemen, just ask to be at least as good as SAP, ORACLE and MICROSOFT.
I think are obvious deficiencies in the documentation, it's not a problem of my knowledge of where the contents.
If we do not recognize areas for improvement never advance.
De: Nhomar Hernandez [mailto:firstname.lastname@example.org]
Enviado el: martes, 12 de agosto de 2014 16:49
Asunto: Re: Reflection about documentation.
On Tue, Aug 12, 2014 at 9:05 AM, Miguel Acebes <email@example.com> 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.
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 .
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¿?¿?¿".) 
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 doc.odoo.com 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 , 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 ;-).