1. Mailing Lists
  2. Contributors
  3. Re: "The plan" to help non technical to contribute documentation on OCA modules

Contributors mailing list archives

contributors@odoo-community.org

Browse archives

Re: "The plan" to help non technical to contribute documentation on OCA modules

Re: "The plan" to help non technical to contribute documentation on OCA modules

Avatar

Re: "The plan" to help non technical to contribute documentation on OCA modules

by
ForgeFlow, S.L., Lois Rilo Antelo
- 17/12/2024 17:45:13
Hi,

For me ignoring the odoo version doesn't look like a good idea, it may be Ok for 90% of the modules in a range of 2 versions (let's say 16-18), but as the range expands and more changes are applied to more core applications (imagine 16-25), maybe it is only a good idea for 30% of the modules that luckily were almost unchanged during all these versions. I don't see how a document with a lot of notes like "do this in versions from 16 to 17 and this other thing from 18 to 21 and then do this other thing from 22" will benefit anyone in the long term.

From my PoV, Odoo itself did it right with the version selector at the top right of the documentation website. We all know that some of the pages are pushed to the next version and not fully updated to be aligned with the new version, but at least the big changes are reflected and I can look at a specific version documentation with no noise.


Also, having to do two pull requests to update code and another to update documentation (yes, many technical people update documentation) can lead to the second one (documentation one) being avoided. What I mean is that we would probably need a good mechanism to reinforce the documentation update linked to a feature change if we go that path...

My 2 cents.

Kind regards,







On Tue, Dec 17, 2024 at 4:58 PM Virginie Dewulf <virginie@odoo-community.org> wrote:
Hello everyone,

I wanted to share some news on this topic. As I asked in my latest email, some of you (Pedro and Jordi in particular) checked the plan and gave their feedback on Github on this specific task/issue (https://github.com/OCA/docs/issues/7). Thanks for taking the time to do so!

As the propose plan and its implications are being discussed and have a broad impact, I would like to bring back this discussion in this mailing list ("it is only fools who don't change their mind" ^^).

I would like to get more feedback from the community on this strategic topic. Many people got involved to make a minimum viable product, define the architecture of the plan, test the prototypes, etc. Let's make it work, together!

Here is the gathering of the current debate. Please, share with us what you think of this, identify what's missing and let's think of a way to proceed. Thanks!

Reminder: Goal of the project
1. Allow consultants to update the documentation in a user-friendly tool
2. Have a beautiful website with a good search features to find and read the OCA modules documentation, in order to share the values brought by the OCA modules, in the end having more contributors to maintain and create new OCA features.

Constraint of the project:
- being practical for consultant/functional profiles
- not adding too much burden to the current contributors (even though a bit of change might be required to make some space to the new profiles)
- being reasonably easy to implement (in human-time and cost)
- being easy to maintain on the long run, as our usual infrastructure maintainers (mainly Stéphane Bidoul) have very little time available for that
- ideally, if new tools are added, other tools must go (cf. previous point), hence the idea of getting rid of the Odoo App Store on the OCA website

Proposed (technical) plan: see https://github.com/OCA/docs/issues/5 for the full picture.

Controversial points:
A. the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). 

B. there will be only one documentation page for all the versions of one module.

Current discussion regarding point A (move the doc from the readme to the Doc repo)
Pros
* unique source of truth in the Doc repo
* no synchronisation needed to maintain the doc updated in the readmes and in the Doc repo (syncs are very complex to implement and maintain because of the scale of the OCA infrastructure)
* this option makes point B possible: The README in a module is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions. Counter-argument: create a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source code

Cons
* Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.
Counter argument: self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).


Current discussion regarding point B (one documentation across all the modules version)
Pros
* easier to manage for functional contributors
* help people find and use OCA modules more easily (having one documentation with all the information is easier for that)
* From several consultant's experience, even if we actually have one Readme per version for a module now, the Readme is not updated from version to version. It is the same (most of the time) for all versions.
Side Note: if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ... The idea is to find everything at the same place and not having to go and compare versions to see the changes.

Cons
* "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile. How to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right? Counter-argument: we haven't seen any edit war to improve the modules documentation so far. If it's happen, it's a good sign. If the refactoring is important, the module will probably be renamed.
* Even Odoo doesn't do that with their documentation, which is "more controlled".
* Risk of errors on the documentation that will confuse readers more than helping them.
* "This is undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation." Counter-argument: if it's undoable in one unique document, why would this be doable in all readme for each versions? We know it's not the case right now so it won't be worst with the new plan.
* Risk of making the developer/semi-functional people's life worst with all these troubles


Attention point:

The 2 paths that we could see from here (sticking to the initial plan versus having one doc/version with a synchro) are not equivalent at all in term of feasibility and impact. Having a synchronisation for the doc cannot be done exactly as it is the case with Weblate because the synchro is one-way only (Weblate is the master of the translations). Here the synchro that is mentioned would require a synchro in both ways (from the PR's on the module's repo triggered by the technical contributors AND from the PR's on the Doc repo, triggered by the user-friendly tool to edit the doc for the consultants).


Last but not least:
Curious to see the current MVP in action?
* the website with only one test module for now: https://oca-docs.netlify.app/
* the CMS Decap access (login with your Github account): https://oca-docs.netlify.app/admin/

Hoping to get more feedback, I wish you a happy end of the 2024 year!

Virginie Dewulf
Executive Director
+32 477 64 17 20


Le mar. 10 déc. 2024 à 14:24, Virginie Dewulf <virginie@odoo-community.org> a écrit :
Hello,

This is a followup email for this email thread:

During the 2024 OCA Days, the OCA Consultants working group presented the status of the Documentation project: how to document OCA modules right now (using the Github workflow) with Julie and Florencia (video here: https://youtu.be/Kw0V_PdBUPg?feature=shared).

In parallel, a prototype of a new tool and process to easily document OCA modules has been proposed by Jairo Llopis, after discussion with Stéphane Bidoul to take into account the full picture of OCA infrastructure.

The goal of this new way of managing the documentation is two-fold:
1. Allow consultants to update the documentation in a user-friendly tool
2. Have a beautiful website with a good search features to find and read the OCA modules documentation

This will impact the way the documentation is managed in the OCA modules. In summary, the documentation of all the OCA modules will be visible on a dedicated website, that will in the end of the transition replace the current OCA App Store. The documentation itself will be stored in a dedicated Doc repository (https://github.com/OCA/docs) and be removed from the readmes of the modules (where a link to the dedicated website will be displayed). Finally, there will be only one documentation page for all the versions of one module.

The next steps are gathered in an issue on Github, called "the plan". Here it is:

To get more information about this, please check the link above. You can also read the latest meeting notes of the Consultants meeting held in November here: https://docs.google.com/document/d/1v23TwOwm9I7w3MNFZo-iCWQxVKedwoVzN9nEyflJVd8/edit?usp=sharing

If you want to share your feedback on this topic, I propose to keep it in the related issue on Github:

Thanks a lot to the consultants working group and especially to Jairo and Stéphane for their help! As you'll see in the plan, there are many "todo"s and help is always welcome.

All the best,
Virginie Dewulf
Executive Director
+32 477 64 17 20

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



--
Lois Rilo Antelo
ERP Consultant Manager at ForgeFlow S.L.

Reference