openerp-expert-framework team mailing list archive

[Xavier Morel <xmo@xxxxxxxxxxx>]

On 2012-02-22, at 04:12 , Ovnicraft wrote:
> Hello OpenERP experts, this email is for request release complete
> documentation for OpenERP web, i found many topics incomplete: installing,
> starting, deploying.
> Its necessary release complete documentation, not just code as you know.
> I recently bult the doc in
> http://readthedocs.org/docs/openerp-web/en/latest/index.html
> You can check it online now.
> 
> Here is a good point when documentation is growing to translate it, i check
> the make file and it does not support translation.
> 
> Please help us with complete documentation.

A few thoughts:

On translation of the technical documentation, I/we do not think there's much of a point. And neither does the community since the translations are basically unmaintained (if they exist at all).

Plus the code, comments and examples are all in english, so it's only making the documentation harder to read. In general, we've found translating technical documentation to create more problems than it solves.

And since the community seems appreciative of openerp-web's documentation being embedded in the project (Simone Orsi already had a compiled version of it [0]), maybe we could split the current "developer book" and move its sections into the various projects (server, addons, web, ...) instead of having a huge monolitic docs repository (the documentation would still get published in the same place, it's just the source which would be moved around).

This would make generating the doc easier (especially the auto/api doc), and it would also be easier to keep doc and code in sync (as documentation changes could be reviewed with code changes in merge proposals, by developers and by the community domain and technical experts). Also correctly matching a code branch and it documentation would be way easier.

On documentation completeness (for 6.1), keep in mind OpenERP Web 6.1 was also a learning experience for us as most of the team had never developed a "major" web application, so there will probably be API changes between 6.1 and the next version. Documenting too many details of 6.1 may also bring trouble.

On the other hand, maybe we shoud document those changes between 6.1 and next version while developing the next version to make porting easy for those who started developing on 6.1 though, what do you think?

[0] http://planet.domsense.com/en/2012/01/openerp-new-web-client-6-1-documentation/