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
MoaHub, Graeme Gellatly
- 18/12/2024 12:10:19
For me the fastest way to document most OCA modules AND have them apply across versions AND have them always current is to use tours which can now simply be recorded, exported, played and could apply per version, I am asking my team to do that for everything now. It not only has the benefit of allowing the user a guided how to of how to use the module, but it also becomes a test across versions and actually makes reviewing PR's easier. IOW, your documentation (tour in this case) becomes part of your test suite. Your test suite becomes part of documentation. Because every version would have its own tour, then you just need to click the version in whatever service/website. You can link whatever version to runboat to try the tour.

In general, yes big changes do happen to modules, not often enough for me, but for the most part the problem they solve doesn't really change. In fact that is probably the bigger issue is when the problem they solve either no longer exists (qweb_mail_templates comes to mind, or product_variant_multi or numerous others) or now only exists in community. 

Obviously there is a technical jump from recording to exporting/committing/testing but it is fairly scriptable. I don't know, but I imagine because they are text based, they might also be translatable. Anyway I don't much care for the detail of where it is hosted etc for end users to access, but I really think tours are quick and will help keep documentation in sync with modules, and also help review.

On Wed, Dec 18, 2024 at 2:42 PM Yoshi Tashiro <notifications@odoo-community.org> wrote:
I find it hard to imagine that having one document per module would work nicely.  For example, we split the sale_commission module into commission, account_commission and sale_commission modules as we did the migration from 14.0 to 15.0.  Organizing the content coherently for before and after in one place for this case would be quite tricky.

What I imagine might work is to implement a non-technical process to let individuals who are not familiar with markdown editing or git create issues for improving the README with contents and images, and let whoever is familiar with markdown and git create corresponding pull requests.

For example:
- A non-technical person creates an issue with a title like "[README][15.0/16.0/17.0] web_responsive", and describes contents to be added/improved.
- A bot links the issue to the open PRs of web_responsive for the corresponding versions as a reminder.
- Contributors of the open PRs should try to incorporate the suggestions of the issue as appropriate.
- Otherwise, someone with the right skills creates a pull request to address the issue, using its contents.

I suppose this approach is user-friendly enough for consultants, and may work with proper guidelines. I am not sure about the implications for the goal of having a beautiful website, though.

Best regards,
-- 
Yoshi Tashiro



On Wed, Dec 18, 2024 at 12:58 AM 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

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

Reference