Community mailing list archives
Re: Reflection about documentation.by
Eric Caudal OCA board Member
So, if enough people are willing to contribute (as it seems) it makes sense for OCA to coordinate a functional docs effort.
My proposal is to:
- Decide how the host these docs and the
- Create an OCA/docs repository for it.
- Nominate a small team of lead contributors.
- Let this team draft the initial skeleton and guidelines.
Both options allow to:
- Are easily editable by non-technical people (click edit, and then save / maybe crate PR directly from GUI)
- Are "hackable": both can the cloned locally and be fed to script for things like creating HTML pages or PDF docs.
Some highlights for the GitHub Wiki option:
- Better page navigation, with a right-hand side index
- Custom sidebars and footers
- WIkis have an option to allow public write access on them
- On existing community projects, just activate Wikis and follow the same Docs guidelines.
Some highlights for the Repository files option:
- Contributors with write access have do be set in the repo's
ACL; but anyone can contribute creating proposals from the GUI
(PRs as usual).
- Support for branches, which can be used for the different
Odoo versions, and maybe for different languages (if decided
- Will need a strategy to better integrate with other community modules docs; for example, adopt a "module/docs/*.rst" document structure that could be mimicked in other modules repos for seamless integration.