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
Moduon Team, S. L., Jairo Llopis
- 02/01/2025 10:33:44
Hi everyone!

IMHO both controversial points, when applied together, reduce the pain that we currently have.

Some current facts:
  • Current OCA docs (aka READMEs) are not always updated.
  • Functional contributors have a very hard time at contributing to those docs.
  • Maintaining version divergences is already very hard for technicians. Asking functionals to do that is a big part of the current problem.
  • When thinking of a new docs system, we have to think about who will write the docs and who will read them.
  • Data duplication is not good for SEO.
  • We want good, up-to-date docs.
So, let's say that we keep the current status quo. We just teach functionals how to use git, write good commit messages, write markdown, use github, switch between branches, do a rebase every now and then, and we expect them to update the readmes. And let's imagine for a second that this happens.

Now they have a task: update docs for 10 modules, across all the 3 versions maintained in their companies. Many OCA contributors just use even Odoo releases, so those versions might be 14.0, 16.0 and 18.0.

Now just do the math: 10 modules x 3 versions = 30 READMEs. With the new system, 10 modules x 1 single doc = 10 REAMEs to update. Conclusion: 1 single doc is more maintainable. And still, versions 15.0 and 17.0 would be forgotten with the older system, while with the newer one they'd also get those changes.

I was sitting down at the table with the functional people expressing how difficult it is for them to contribute to OCA. At the same table were some very experienced contributors, including OCA Board members. We're trying to improve a problematic situation we have right now. Of course, current controversies came to the table. Some of our thoughts:
  • Is it really that important that the screenshots you see are for the same version of the module that you're using?
    • No. Many times, modules are migrated and screenshots are not updated. As long as the module works  mostly the same, it's good enough.
    • Besides, you can have a custom theme. Or even you could use Odoo EE and all your UI will be different.
  • Is it really that common that modules behave significantly different between versions?
    • It happens, but it's the less common case.
So, if we favor the most common case (the module does mostly the same across versions) and still have a way to handle the least common one (significant UX divergences), we still are winning.

So, are we really crazy to tell you that we can maintain a single doc? Let's see how others do it.

When I think of good docs, I think of Gitlab. Their docs are awesome. How do they handle the different versions? I'll showcase some examples below, so we can learn from them. FWIW I'm currently browsing the latest Gitlab docs, which officially target v17.8. Also FWIW, they have a version dropdown. I used Gitlab for about 10 years and I never had to click that dropdown.

These install instructions will tell you which postgres version to use. They have several gitlab flavors, and they maintain 4 major releases. However, all the info is gathered in a single docs page:
image.png

Now, think about it. Is it easier for a writer (who is not a programmer) to maintain 4 different branches of docs with different installation instructions? Or just to maintain the latest one, which has a table indicating data for all versions? Of course, the latter.

How do they handle feature changes? See:
image.png

Again, if you're using Gitlab 16.0, it's still better for you to read these docs than the docs for 16.0, because you don't only know how it works, but how it has evolved since the version you're using. This helps you prepare for that. As a docs reader, this structure is way better. For a writer it's also easier to maintain.

Now, let's think about deprecations and removals. They have a page dedicated to that. Currently I'm browsing docs for v17.8, but I can see info for past and future versions (up to Gitlab 20.0!). Future versions! Of course! It's relevant for me to know if something will be deprecated, even if it still works. Brilliant.

Apart from that, deprecated features still have a red warning about their status. One example:
image.png

The fact that docs are centralized isn't a big problem IMHO. If you need offline access, you can clone the repo and browse those docs offline. And the fact that the module docs are scattered across various places (oca/docs and the module code) would be "less worse" than having to maintain up-to-date per-version readmes.

An extra point of having centralized docs is that you can exit the current constraints of "just a readme per module", and start having use-case-based docs. Imagine a webpage where you can explain how to use OCA for having better inventory management, for boosting sales, for better privacy, etc. An use-case-based page can just link to the individual modules needed to get that use case done. That's impossible with the current structure.

So, summarizing:
  • Current workflow
  1. Is easy to "fire and forget". You push the module, it has the readme, it works, done. Never look back. Yes, we knew that taking technicals out of something comfortable for them would produce these kinds of reactions.
  2. When you migrate a module, most times docs are not updated accordingly.
  3. Has everything self-contained.
  4. Is per-version.
  5. Is hard to maintain. As a consequence, it's not properly maintained.
  6. It's impossible to use by functionals. Thus, writing docs is an extra burden almost exclusively on the shoulders of coders.
  7. Docs are written by whoever wrote the module. Sadly, this impacts negatively on the quality of the docs. They communicate with more technical words. Maintaining videos and pictures is burdensome for them.
  8. Translating is impossible.
  9. Merging changes involves irrelevant nitpickings (commit message, formatting, etc.)
  •  New workflow:
    1. Can be equally easy when adding a new module (due to a sync that could import that readme as the starting docs for the module). When adding a new feature, it can involve adding another PR to docs. That PR, however, doesn't have to be done by the programmer.
    2. When migrating a module, if it behaves the same, there'll be nothing to be done. Otherwise, see point 1.
    3. Docs centralized.
    4. Single page. Relevant per-version changes kept on the same page.
    5. Easier to maintain. As a consequence, they'll have more maintenance.
    6. Functionals can learn to contribute in a 5-minutes video. Less copywriting burden for coders.
    7. Docs are written by people that use the module. They communicate without technicisms. They value pictures and videos as that's their daily life. Docs quality will be better.
    8. Translating is possible (not yet in the MVP, before you ask).
    9. Functionals can merge without nitpicks. Reviews are done purely visually. The outcome is an SSG with very little attack surface. Git is just a DB.
    The new workflow is not perfect, and it might require an extra PR every now and then. However, IMHO it opens many doors for improvement that are currently closed.

    Many have predicted "catastrophes" with this idea. However, it's good to reflect on the pain points we currently have. Why not also try to predict how much better this would be? When I think about it, I see it's worth trying.

    Reference