Community mailing list archives
Re: Reflection about documentation.by
Elico Corporation, Eric Caudal
I would definitively go for the option that allows translations. Nevertheless I have the feeling that translated documents are very few and very difficult to maintain over time.<blockquote cite="mid:53EC7C74.email@example.com" type="cite"> Fabien made it clear that building functional/end user docs will not be the priority for Odoo.
On 08/14/2014 05:14 PM, Daniel Reis wrote:
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.