1. Mailing Lists
  2. Contributors
  3. Re: The OCA Functional Working Group asks for your help!

Contributors mailing list archives

contributors@odoo-community.org

Browse archives

Re: The OCA Functional Working Group asks for your help!

Re: The OCA Functional Working Group asks for your help!

Avatar

Re: The OCA Functional Working Group asks for your help!

by
Moduon Team, S. L., Jairo Llopis
- 24/04/2024 14:23:33
Hello Julie.

Thank you very much (and the rest of FWG) for the work in this regard. Indeed better tooling for functional docs would help a lot!

My suggestion would be to have a plain hierarchy where OCA's docs exist.

The backend for that hierarchy could be some SSG that renders those Markdowns into something beautiful.

I have experience with 2 SSG: hugo (I use it for my blog) and mkdocs (I use it for Copier docs). I think that for our purpose, mkdocs fits better. One nice thing about those 2 SSGs is that both support translations (which is something that, surprisingly, Odoo built-in README doesn't).

Regarding the UI for interaction, in my blog I use https://decapcms.org/ which is open source and very simple to setup. It basically provides an alternate UI for SSG, and the backend for that UI is github or gitlab (using its API as a controller, using Git as a storage backend, and Markdown as a storage format). It allows meda files management, and it even includes support for what they call "Editorial Workflow", which means that new posts or pages are added in a PR that advances through different stages (and it uses github labels to know the stage).

So basically you'd have the same github PR UI for us techies to keep on going with our same code/review/merge flows we know and love, but you'd have let's say another UI for Github that would do the techie work for you if you're not a techie (or are one of those techie weirdos that love fancy UIs).

Then just have a CI that renders those markdowns that land in the main branch of https://github.com/OCA/docs into a website published at oca.github.io/docs when merged.

Even nicer, each module could have its space, and our dear bot could just publish our module's READMEs as the landing page for the same modules in that same project when doing its post-merge jobs.

Of course this requires some setup that could be completely saved if you just go to wordpress.com, open an account and pay whatever they ask you. Or if you open up a google docs per module where functionals can go and write. Or you could even install a wiki system. Yikes, we could even create wiki modules for Odoo and install them in odoo-community.org and let our contributors contribute there the wiki.

Many options, I hope some one of those help :)

Reference