Skip to Content
  2. Mailing Lists
  3. Contributors
  4. Re: The OCA Functional Working Group asks for your help!

Archives

Contributors

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

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

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

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 :)
by Jairo Llopis - 02:25 - 24 Apr 2024

Reference

  • The OCA Functional Working Group asks for your help!
    Do you know of any tool that could easily allow to edit and create PRs of README files in GitHub without the need of having GitHub knowledge? Something similar to what Weblate does for .po files ?

    Hello everybody!


    During the last OCA Days, the OCA Functional Working Group (FWG) presented the work made on the Documentation Project.


    This project was created by the FWG to help and attract functional people to contribute to modules documentation.


    2 main options were analyzed


    • Using the existing Read Me file in the code so we have only one module documentation which regroups technical and functional information.

    • Using the GitHub Wiki on the repositories which could be really easy to put in place and use.


    The decision was made to use the existing Read Me but to convert it into Markdown so it could be easier to use and to add images.


    Following this decision, an issue was opened in GitHub about the use of the Wiki instead of Read Me : https://github.com/OCA/maintainer-tools/issues/606



    BUT, we still have a big issue regarding this solution: the process to contribute to Read Me is really, really complicated for non-technicals.  


    1. You need to have a Github account and sign the OCA CLA

    2. You would have to fork the repository (well, here we already have lost most of the non-technical people).

    3. Then edit the files of the Read Me using the Web Editor (so you can add images).

    4. Download your images in the right folder than insert them into the file by Drag & Drop

    5. Create a commit and a PR.

    6. Finally, the changes would need to be approved by contributors who have those access rights.



    So, we were thinking: if we add a Markdown tool that can be used to edit Read Me files and automatically push the changes into GitHub a little bit like the Weblate tool, we could combine the PROS of both options analyzed.



    Does anyone have any idea of this kind of tool?


    Thank you in advance for your help.



    The OCA Functional Working Group

    fwg@odoo-community.org



    by Julie LeBrun - 07:31 - 23 Apr 2024