Community mailing list archives

Re: Reflection about documentation.

Daniel Reis
- 08/14/2014 05:08:04
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:
  1. Decide how the host these docs and the collaboration process.
  2. Create an OCA/docs repository for it.
  3. Nominate a small team of lead contributors.
  4. Let this team draft the initial skeleton and guidelines.
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.

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.