Community mailing list archives

community@mail.odoo.com

Re: Reflection about documentation.

by
Fabien Pinckaers (fp)
- 08/13/2014 13:53:21
> I can do some research on that, how other projects do...

You can fill in this pad:
  http://pad.odoo.com/p/doctoc

>     6/ We will clean the platform and add missing features from readthedoc
>     but we will keep the design of bootstrap. (the only things we
>     need is to connect transifex to the github repo and the Edit in
>     Github button)
> 
> This is fine, as long as the plattforms most important objective is
> convenieance, ease of navigation and readibility (!).

Yes, we agree. I think a great usability requires a bit of control. For
instance, the API guide should have a different CSS like this:
  https://stripe.com/docs/api

And probably links to demo.odoo.com so that you can test queries in the
documentation directly, like the facebook api doc.

> I investigated a bit on inline code documentation, and it seems
> that http://sphinx-doc.org/man/sphinx-apidoc.html, which is already
> imported in the actual doc build setup can probably built the api
> reference and a class glossary, we all starve for.

In XMO's branch, the ORM reference is already documented from the code.
Unfortunatelly, it does not work for everything; it's impossible to
document views from the code. For this, we will probably update and port
to RST the current technical memento that is quite good in its structure.

> This would you bring some benefits (over another api documentation approach)
> - Get complete documentation near the code and make it part of the code
> review (sic!) (this is not inforced yet, as I noticed on some ambigous
> new-api documentations)

Auto-generated docs are usually boring to read. How would you document
views, workflows, ... We did it for the ORM and it was a nightmare (we
even had to reorder some methods in the code so that the ToC is ok)



-- 
Fabien Pinckaers
Odoo Founder

Phone: +32.81.81.37.00
Web: https://www.odoo.com
Twitter: @fpodoo

Instant Demo: https://odoo.com/start