Community mailing list archives
Re: Reflection about documentation.by
Eric Caudal OCA Board Member
Fabien made it clear that building functional/end user docs will not be the priority for Odoo.
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:
Starting with #1, this is a "technical" decision take: it can either use GitHub Wiki pages, or use Repository files to host the docs directly as pages in the repository.
- Decide how the host these docs and the collaboration process.
- 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 that way)
- 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.