Open norlinhenrik opened 7 months ago
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
Would be a great step to add images, videos, better and updated documentation. Good suggestion! ❤️
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:
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.
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).
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.
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 :
Wiki.js or external tool
GitHub Pages
Wiki GitHub : https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages
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
Is your feature request related to a problem? I find the PR workflow to be a barrier for contributing to the documentation. Who are willing to take the time for this?
Describe the solution you'd like Traditional encyclopedias, written by a few professionals, were largely replaced by Wikipedia, written by normal people. Inspired by this, I would like to encourage OCA to create a wiki where non-techincal users may easily contribute with documentation.
Describe alternatives you've considered
What do you think?