Contributors

• Re: Discover the OCA priorities for 2021 proposed by the board

  I don't know but I feel like any standard solution won't work for us.

  
  

  In a normal software project, you just have 1 branch (maybe 2: devel/stable). Then you add sphinx/mkdocs on a separate folder and docs live happily with your source code. Besides, those tools analyze your docstrings and autogenerate docs. Each repo contains 1 package, which has a single evolving version that follows a standard schema such as PEP 400, semver, calver, etc.

  
  

  OCA has a workflow that is very alien to general github workflow:

  1. Code is spread across different repos.
  2. Each repo has different modules which can be tightly or loosely related among themselves and among modules that might exist in other repos.
     
  3. Each module has its own version. Which, BTW, means nothing in reality and follows a different schema imposed by Odoo and some OCA members.
     
  4. Each repo has multiple maintained versions of each module, one (or zero) per branch.

  I think this is a deeply rooted problem across the whole OCA that hinders contributions and makes any move hard to achieve. I've tried to fix that in the past without success, so I don't care anymore. It's the OCA we have and I have to accept that.

  
  

  So, having all that said, I think that the only way this could work is stick as it is: one README per module/version pair.

  
  

  Odoo docs situation is today less crazy, so in case we have some functional stuff to document, if possible, the place to do it would be https://github.com/odoo/documentation

  
  

  IMHO user docs should be avoided and, instead, modules should be self-explained within the UI. That goes through having friendly empty pages, tours, help tooltips, self-explained dialogs, res.config.settings dialogs, etc. Just make the module obvious and save documentation.

  
  

  For other kind of cross-module, cross-repo, deployment, etc, kind of docs, possibly a single mkdocs repo could be deployed. As it wouldn't be coupled with any specific repo, odoo version or module, it wouldn't need any versioning or branching: just one main branch and build on each commit.
  

  ---

  by Jairo Llopis - 11:21 - 25 May 2021

• Re: Discover the OCA priorities for 2021 proposed by the board

  Ok, I'm agree with you too.

  
  

  Now, I'm understanding that the documentation project take in account many things, besides Functional/Technical docs, like:

  
  

  - Transversal topics ( queue, connector, connector-odoo2odoo ...) depending the Business Objectives and the Technical requirements, so it depends on the specific implementation. So, maybe some sections with recipes for different Business Cases should be appreciate.

  
  

  - Versioning documentation is another gap, for example ReadTheDocs, like many others, manage versioning/branching/languages... and can be integrated with GitHub easily.
  

  
  

  I appreciate your answers,
  

  
  

  
  

  
  

  El lun, 24 may 2021 a las 11:42, Jairo Llopis (<jairo.llopis@tecnativa.com>) escribió:
  

  I agree with Tom.

  
  

  Also, having that /docs folder would make migrations even harder. Would make it very hard to find docs of several modules. Would force us to maintain one docs version per module version.

  
  

  
  

  El sáb, 22 may 2021 a las 18:42, Tom (<tom@sunflowerweb.nl>) escribió:
  

  I am with you except for 1 thing: I think documentation is central and not tied to specific repositories. Because if you want to make a doc about one topic such as "syncing data" it will involve many repositories: queue, connector, connector-odoo2odoo, server-tools, bank-statement, edi....
  
  The e-learning system is good but it is not so strong in wiki-like editing.
  
  The "Migration" docs and "OCA guidelines" have become powerful docs that are much referred to; i think a central place such as that would be better for the docs, and then organized per each topic. Either on Github Wiki or on Github pages.
  

  _______________________________________________
  Mailing-List: https://odoo-community.org/groups/contributors-15
  Post to: mailto:contributors@odoo-community.org
  Unsubscribe: https://odoo-community.org/groups?unsubscribe
  

  
  
  --
  

  Jairo Llopis
  

  _______________________________________________
  Mailing-List: https://odoo-community.org/groups/contributors-15
  Post to: mailto:contributors@odoo-community.org
  Unsubscribe: https://odoo-community.org/groups?unsubscribe
  

  
  
  --
  

  https://github.com/JuanDCG

  
  

  ---

  by Juan Del Castillo Gómez - 02:31 - 24 May 2021

• Re: Discover the OCA priorities for 2021 proposed by the board

  I agree with Tom.

  
  

  Also, having that /docs folder would make migrations even harder. Would make it very hard to find docs of several modules. Would force us to maintain one docs version per module version.

  
  

  
  

  El sáb, 22 may 2021 a las 18:42, Tom (<tom@sunflowerweb.nl>) escribió:
  

  I am with you except for 1 thing: I think documentation is central and not tied to specific repositories. Because if you want to make a doc about one topic such as "syncing data" it will involve many repositories: queue, connector, connector-odoo2odoo, server-tools, bank-statement, edi....
  
  The e-learning system is good but it is not so strong in wiki-like editing.
  
  The "Migration" docs and "OCA guidelines" have become powerful docs that are much referred to; i think a central place such as that would be better for the docs, and then organized per each topic. Either on Github Wiki or on Github pages.
  

  _______________________________________________
  Mailing-List: https://odoo-community.org/groups/contributors-15
  Post to: mailto:contributors@odoo-community.org
  Unsubscribe: https://odoo-community.org/groups?unsubscribe
  

  
  
  --
  

  Jairo Llopis
  

  ---

  by Jairo Llopis - 11:41 - 24 May 2021

• Re: Discover the OCA priorities for 2021 proposed by the board

  I am with you except for 1 thing: I think documentation is central and not tied to specific repositories. Because if you want to make a doc about one topic such as "syncing data" it will involve many repositories: queue, connector, connector-odoo2odoo, server-tools, bank-statement, edi....
  
  The e-learning system is good but it is not so strong in wiki-like editing.
  
  The "Migration" docs and "OCA guidelines" have become powerful docs that are much referred to; i think a central place such as that would be better for the docs, and then organized per each topic. Either on Github Wiki or on Github pages.
  

  ---

  by Tom Blauwendraat - 07:41 - 22 May 2021

• Re: Discover the OCA priorities for 2021 proposed by the board

  Hi Contributors,
  
  I don't hesitate contribute with my strategical vision and I suggest it:
  
  - Create one /docs folder per repository instead in readme ( and point the readme to docs page )
  - One subfolder for technical documentation and another with functional with only the markdown files.
  - In /docs folder create a static web page with any generator and render and host it with GitHub pages.
  - Create one subdomain per repository pointing to webpage. In this way, making it web page is more searchable and accesible to people.
  - To Centralize all the How-To set up the e-learning module at OCA system.
  - In the e-learning module you can point content to each subdomain with each web page, in a embeded web page way.
  - In this way you can create a course path for functional or technical documentation based on this embeded web pages.
  
  This is my approach, with the e-learning system you can also do gamification, certification and promote the OCA mission.

  
  

  
  

  
  

  
  

  
  

  
  

  El vie, 19 mar 2021 a las 21:57, Virginie Dewulf (<virginie@coopiteasy.be>) escribió:
  

  Hi Tom and other contributors,

  
  

  Thanks a lot for your feedback! This post received a very nice welcome, it's really motivating!

  
  

  I keep note of your ideas about helping functional people get involved and participate to communicate the high value of OCA modules.

  If you're motivated for the first article (we can decide later on which platform/way of keeping this content) about the import/export module, that could be a first content to directly try and see how to diffuse it!

  
  

  We can keep in touch (outside from this mailing list).

  
  

  
  

  To the other contributors: if any other ideas/comments come to your minds, don't hesitate!

  
  

  Have a nice end of week and super cool week-end!

  Virginie

  0477/64.17.20

  
  

  -------- Message initial --------

  De: Tom Blauwendraat <tom@sunflowerweb.nl>

  Répondre à: Odoo Community Association (OCA) Contributors <contributors@odoo-community.org>

  À: Contributors <contributors@odoo-community.org>

  Objet: Re: Discover the OCA priorities for 2021 proposed by the board

  Date: Wed, 17 Mar 2021 09:47:32 -0000

  
  

  PS. Instead of blogs, which are perhaps a bit flighty and lose their actuality value over time, it could also be some kind of permanent wiki or github-based website, which is updated and community-reviewed as time goes by, with the latest insights per functional topic and Odoo version.

  Anyway, ideas ideas... good luck in the new board for 2021!
  

  Op 3/17/21 om 10:38 AM schreef Tom Blauwendraat:
  

  Hi Virginie

  In the post you are mentioning people to react below the blog post, but I can't... so then here:
  

  As a part of communication - maybe a method can be to make a platform that facilitates functional people to write attractive documentation/blogs/howto's about solving Odoo problems with OCA modules. For one, this could supplement the thorough lack of documentation on Odoo CE; but also, if consultants and clients read these blogs with examples and understand better that OCA modules are better than alternatives, because they:
  

  - usually solve problems in the best way, as there is hard-won community consensus on their design
  - are designed to interoperate together as a holistic eco-system
  - are extendible (even better than most Odoo modules are)
  - are quality-controlled
  - are OpenUpgradable
  - etc.
  

  Then they would understand better why it can be commercially more interesting to choose OCA modules and avoid technical debt, then go for the latest and greatest Odoo version supported by some crude customizations and App Store modules, and become disappointed in Odoo in the long run. And then, they would also become motivated to financially support OCA.

  A case in point is for example the import/export modules in the "queue" repository - I'm seeing so many inferior hand-rolled syncing implementations lately, that I'm very motivated to write a furious blog to tell everyone to stop doing that and build on the OCA solution. But now, aside from starting my own blog on the subject, I wouldn't know where to place such an article.

  Tom
  

  Op 3/17/21 om 10:12 AM schreef Virginie Dewulf:
  

  Hello contributors,

  
  

  Here is our latest blog post to present the 2021 OCA priorities proposed by the Board:

  https://odoo-community.org/blog/the-oca-blog-1/post/what-will-the-oca-community-do-in-2021-109

  
  

  Don't hesitate to come back to us/me if you'd like to give your feedback!

  
  

  Have a nice day,

  -- 

  Virginie for the Board

  _______________________________________________
  Mailing-List: https://odoo-community.org/groups/contributors-15
  Post to: mailto:contributors@odoo-community.org
  Unsubscribe: https://odoo-community.org/groups?unsubscribe
  

  _______________________________________________
  Mailing-List: https://odoo-community.org/groups/contributors-15
  Post to: mailto:contributors@odoo-community.org
  Unsubscribe: https://odoo-community.org/groups?unsubscribe
  

  _______________________________________________
  Mailing-List: https://odoo-community.org/groups/contributors-15
  Post to: mailto:contributors@odoo-community.org
  Unsubscribe: https://odoo-community.org/groups?unsubscribe
  

  
  
  --
  

  https://github.com/JuanDCG

  
  

  https://github.com/TerradooCloud
  

  ---

  by Juan Del Castillo Gómez - 04:41 - 22 May 2021

5 more replies