Community mailing list archives

Re: Reflection about documentation.

Hertford Developments Limited, Kurt Haselwimmer
- 08/14/2014 05:51:19
The technical details of hosting and editing the documents is far less important than the purpose of the documentation and figuring out a way for all members of the community - that means users, new and old as well as well established partners of Odoo to contribute. 

By contributing I also do not mean this mean only writing content - this also means ways for suggesting topics, identifying weaknesses in non-existent or draft documentation, editing and criticizing content. Some contributors might find this painful.

However before the OCA tries developing a system to allow a large and disparate group of people who to reinvert parts of a wheel that has only just been spotted as broken or perhaps even non existant the simpler alternatives should be explored....

If one person (Greg Moss) can write a completely coherent and readable introduction to many of the features of openerp v7 (Working with openERP, packt publishing) is it not feasible to consider a crowdfunded project to pay him/ packt to 1) update the book for v8 2) write a book aimed at the next level of competence 'advanced working with OpenERP/Odoo'. 

I see absolutely no reason as to why Odoo SA cannot make a contribution (even a major one) from their marketing budget to help fund such a project, with additional crowd sourced funders receiving a copy of the draft texts early, and the final texts at a significantly reduced overall price.

This way the members of the OCA and the community can concentrate on getting on with the things that they wish to focus on, whilst making small financial contributions that will all add up to getting the documentation job done.


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.


Post to: