Contributors

Thanks Jairo for this extensive explanation of pros and cons, and the examples.
I was at that table during the OCA days: I was not entirely convinced then as I'm not entirely convinced right now.

I also tried a prototype of this new workflow and I can say that you and others put a lot of effort into it for sure, thanks again for that.

In my opinion the new workflow is trying to fix many problems all at once, but I think that we should keep the focus on the one problem at hand:

Allow consultants to update the documentation in a user-friendly tool

and then move to others because it's easier to agree on fewer things at a time.

As you explained, there are multiple issues right now:

• functionals are not able to easily update the README of a module
• a module has a different README in each version
• migrations do not update the README properly
• translations in README can't be done

I think that right now we should focus on letting functional people update a module documentation (README) easily, let's try to solve only this problem first, then move to others.

In order to fix this, and only this, there was one proposal that I did like at that table: add a button in the README that pops up an editor and lets functional people edit the README and seamlessly create a PR.

It was discarded then because it did not solve version misalignment but that should be another step towards the ultimate documentation solution.

I think this would be much easier to implement and roll out because it does not need a new repo or a new docs database because everything would be on the fly.

On a side note, what about moving to a discussion in https://github.com/orgs/OCA/discussions? I think it would be easier to edit/manage/reply-to than emails.

On Thu, 2 Jan 2025 at 10:37, Jairo Llopis <notifications@odoo-community.org> wrote:

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:

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:

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:

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.

_______________________________________________
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

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:

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:

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:

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.

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