WIKI for documentation

[norlinhenrik]

WIKI for documentation

[victor-champonnois]

I agree that using Wiki rather than PR to readmes would remove a big barrier to functional contribution. Does the OCA Functional Workgroup has an opinion on this ? @TumbaoJu

[Shide]

Would be a great step to add images, videos, better and updated documentation.
Good suggestion! ❤️

[yajo]

I also find that contributions to READMEs are a little big barrier, even now that some are on markdown. In my team, functionals usually review the README, or even write it, but at the end a technician pushes it to OCA.

It is particularly frustrating in the sense that we have one code base per odoo version, which makes it hard for devs, but more even for functionals to know where to find instructions.

My suggestion would be:

1. Enable public "wiki" feature in our github repos. It's the easiest way to get from zero to wiki.
2. In the module templates, auto-add a badge that points to the correct place in the wiki. Of course, the badge will point to a non-existing page until somebody decides to create it. But at least, there'll be an official wiki gathering point.
3. Discourage wiki-per-version. Just document the module itself. If something is only on some version, just indicate it with some kind of comment.

Possible problems: abuse. However people could abuse already through PR bombs or offensive comments and we don't have such a big problem on that. I guess we can handle it later if/when happens.

[victor-champonnois]

Discourage wiki-per-version. Just document the module itself. If something is only on some version, just indicate it with some kind of comment.

This is what we started to do in our doc, but it tends to hinder readability as the number of version grows, so we switched to one doc per version. It might be preferable, even if some versions are not up to date (in which case it should be indicated).

[Shide]

We must think that the module documentation also serves as in-odoo documentation.

Separating the files as the technical teams does, could help to split the work and will serve to avoid the headers (buttons) on the README file.

When PR [FIX][17.0] oca_module is merged, ocabot will the contents of the code files into the repo/oca_module/17.0/xxx.file files.

When repo/oca_module/17.0/xxx.file is updated, after 1h (to avoid an avalanche of commits), ocabot will update the contents of the files as Weblate does.

[TumbaoJu]

Hello everybody!
Thank you for all your comments and suggestions. As you know, we have been working on OCA modules documentation and we are open to all ideas.

We explored different avenues for the module documentation such as :

• Github Wiki: https://docs.github.com/en/communities/documenting-your-project-with-wikis
• GitHub Pages : https://pages.github.com/
• https://squidfunk.github.io/mkdocs-material/
• https://js.wiki/ : integrated with GitHub

Wiki.js or external tool

• Would need more work to put in place

GitHub Pages

• Works with RST files, a lot like the Read Me on the modules, so less available / user friendly, difficult to upload images (complicated process)
• Works with PR and merge process, so need approval

Wiki GitHub : https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages

• Easy to use
• Written in Markdown with editor and preview
• Clean and unify page layout
• Easy to add images by drag & drop
• Already available on the repos GitHub
• We could add an automatic link to the wiki page on the read me (top bar) like the links to Runboat for example.
• Ready to use (except for the automatic link in the Read Me)
• No approval / PR process, everybody can contribute
  -- Less of a risk because it is only documentation

So our first recommandation was to try and test the Wiki on the repositories.

We did a bit of tests on that but then the idea of having 2 different places for the documentation (The Read Me AND the Wiki) became a problem hence the idea of ​​using the Read Me but converting it into a more accessible format.

We are still working on "How can we make this more accessible to functionals".

So thank you for all your ideas. We will take it into consideration.

@manuelfcordoba @florenciafrigieri2 @lfreeke @francesco-ooops @vdewulf