Community mailing list archives

Re: Reflection about documentation.

David Arnold
- 08/13/2014 12:33:46
3/ We will move our efforts on the technical doc to a separate
repository with public write access. We initially put it in a
odoo/odoo branch fork. But, for access rights, it's better to have
all docs in a separate repository.
​Very good! This will boost community dynamic, as it seems everyone is scratching itches here...​

4/ Can someone contribute to restructure the existing documentation
into a new and clean structure? If someone is ready to do this
(around 20 hours of work), we can discuss together on how to do it.
I can do some research on that, how other projects do...

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 (!). rtfd can be integrated on you domain, if you might change your mind on maintaining another css theme, it is clean optimized and batlle proven. Missing features, as the one you mentioned can easily be contributed. I'm sure in no time, color scheem could be adapted to Odoo corporate colors, without loosing the built in presentation best practices. There is valuable knowledge and experience built into their system, and all they do at rtfd is documentation... Think about! :)

I investigated a bit on inline code documentation, and it seems that, which is already imported in the actual doc build setup can probably built the api reference and a class glossary, we all starve for. Provided that within internal R&D and development proces, class documentation is emphaziesed and enforced stringently.
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)
- marginalize maintaniance cost (as doc is born at the point information itself is generated)
- Build documentation automatically, so no need to write any extra reference...

El Alemán S.A.S

David Arnold BA HSG / Gerente
315 304 13 68/ david²

El Alemán S.A.S Office: +57 (1) 651 3766 / Fax: +57 (1) 651 3772 
CRA 13 93 40 P4, Bogotá, Colombia


This e-mail message may contain confidential or legally privileged information and is intended only for the use of the intended recipient(s). Any unauthorized disclosure, dissemination, distribution, copying or the taking of any action in reliance on the information herein is prohibited. E-mails are not secure and cannot be guaranteed to be error free as they can be intercepted, amended, or contain viruses. Anyone who communicates with us by e-mail is deemed to have accepted these risks. El Aleman S.A.S is not responsible for errors or omissions in this message and denies any responsibility for any damage arising from the use of e-mail. Any opinion and other statement contained in this message and any attachment are solely those of the author and do not necessarily represent those of the company.