Sign in
Try it free
  1. Mailing Lists
  2. Community
  3. implementing - gitchangelog to odoo and its modules

Community mailing list archives

community@mail.odoo.com

Browse archives

The ethics to answer questions

Removing Postgres

implementing - gitchangelog to odoo and its modules

by
Andi Becker
- 05/21/2016 20:37:02
Refering to the Thread Re: Odoo: Understand Culture & Management 

I think it would be good to discuss the "Documentation and Changelog" points for developers and newcomers here in a separate Thread.

IMHO the documentation of the code and being able to read the changelogs easily is very important for an Open Source Community which should evolve. It can only evolve if constantly also new people will join with their new ideas an Open Source Product and therefore the way Odoo Changes get documented must be much better documented and easier to read! 

This would also reduce lots of Questions on the mailing lists which others (who often have been here long time) might think don't belong there as they are to easy. Actually the fact that such "easy" "read the code" "newbie" etc. questions get asked shows that the documentation is not what it could and should be and that especially newbies struggle a lot to fit in that community.

Harsh comments often keep those new developers away from Odoo and are additional having a very bad impressions of its community to those (i.e. potential customers, Odoo users) reading those Threads and the result will be that nothing will evolve as it could evolve by allowing simple questions to be asked also on mailing lists. And of course they should get answers if they are so simple - which might should get discussed in another Thread - The Ethic of answering simple questions - later.

This Thread here should be only about the constant documentation of the changes in Odoo!

Cody Kitterman wrote:

Robert:
     What do you think about Odoo implementing something like gitchangelog: "use your commit log to make beautiful and configurable changelog file"? 
It's compatible with Python 2/3, works on Linux/BSD/MacOSX, and it's default output is ReSTructured text (which is what the doc's are using now).
It could be made to fit nicely with Odoo's Commit message conventions, assuming they were expanded (SEE "Action", "Audience", "Tags"), and would address some of your concerns:
"the actual documentation was a huge source of frustration. Just this week one of my office colleagues who tried to learn how to create a web site creator snippet gave up in frustration. The documentation is just wrong ..
And I learned myself that the JavaScript API documentation is mostly V8 based and of little value for V9. Unless, of course you know what has changed between v8 and v9. For which I found no documentation at all.."
Developers could review these and update their modules and Odoo's documentation.
R/S

Nhomar Hernandez wrote:

Again.
Read the code please!, do not make statements just because people does not look in the right place.
Folder doc into the mail module:
https://github.com/odoo/odoo/tree/9.0/addons/mail/doc
Here:
https://github.com/odoo/odoo/blob/9.0/addons/mail/doc/tracked_field.rst
You can improve what you actually know and make a PR "It is very welcome".
Regards.

I think those are two different things developers of Odoo like ours here and as I see also others around the world.
  1. The documentation which Nhomar mentions does not help a lot with localise actual changes
  2. Cody mentioned a very good solution to fix actually that problem.
  3. It would be great to have that integrated in Odoo. 
Those are the Three Points I see in the argumentations.

From my own experience while working with Enterprise Open Source Solutions I think if a module/modules like we have extensions doing that in TYPO3 would be available for developers, than all of those problems could be solved easily and beside that even customers would get a better documentation. There would be no need to search on multiple places in the internet - Google is your friend way!

Here are the very helpful 2 TYPO3 Extensions I am talking about and they might be an inspiration to accomplish the same for Odoo. Also a gitchangelog style doc could be integrated that way for the core and each module to be read inside Odoo itself! 

From our experience in TYPO3 Projects I would say that since we work with those integrated docs development speeded up as much less time is needed to search in multiple google threads which are often even not showing an answer.

Please have a look at:


Sphinx Python Documentation Generator and Viewer

Installs a full-fledged Sphinx environment within your TYPO3 website. Builds and renders Sphinx/reStructuredText-based projects such as extension manuals, official reference guides or your own in-house documents as HTML/JSON/PDF either from TYPO3 Backend or from command-line, as you prefer. Features a reStructuredText editor with cross-reference browser and syntax highlighting.



Sphinx Documentation Viewer Plugin

Seamlessly embeds Sphinx/reStructuredText-based documentation into your TYPO3 website. Instead of publishing your various manual, in-house documents, guides, references, ... solely as PDF, render them as JSON and use this extension to show them as part of your website to enhance the overall user experience and Search Engine Optimization (SEO). Lets you merge the chapter structure with the breadcrumb menu and much more. Documentation styles automatically inherit from your corporate design.

==========

Andi







Follow-Ups