Introduction 

After the last OCA Days in 2022, a group of functional people from different countries and companies decided to work together to improve functional contributions in OCA.

Documentation of OCA modules has been identified as one of the main areas where functionals’ expertise can be useful. 

Our primary goals with this project are:

• to make it easier for everyone to understand what is the purpose of a module and how to use it 

• to provide guidelines on how to write good and complete documentation

• to improve access to editing and contribution of module’s documentation for functional people (eg: adding screenshots)

What are the changes?

• Implementing Markdown in place of RST for Read Me

• • A great module documentation has screenshots so the reader can understand better how to use the module. The problem is that it is difficult for a functional person to add screenshots into an RST file.  You must upload the image in a folder (and you have to know which one ;) ), then you need to know how to put the link to the image, and if you make a mistake, the image doesn't show…

  • Markdown files are supported by GitHub and this format allows you to insert a screenshot easily by Drag & Drop.

  • Markdown provides a simple and unified layout (as RST do) so we don’t lose this advantage.

  • GitHub provides a Markdown editor tool so you don’t even have to learn the syntax (but, we tell you, it is very easy to learn ;) )
    

• Providing guidelines for documentation

• • We are still working on the Guidelines but we will have a first version ready for the OCA days!

• Enhancing Readme template

• • Adding some information into the description of the fragments so anybody (functional or developer) can understand the usage of each fragment.

  • Adding a new CONTEXT fragment. This new fragment can then be used to explain the why (context, use cases) of the module.

What are the impacts of those changes?

• The Read Me’s template files have been converted to Markdown.

• We will be converting, in the next weeks, all Read Me files to Markdown for all repositories in branch “16.0”. 

• Read Me in RST will still be accepted but we strongly recommend to use Markdown for all the reasons enumerated previously.

• For the branch “17.0”,  only Markdown files will be accepted.
  

 How to proceed in case of migration of a module?

• You can convert existing readme fragments from RST to Markdown for a whole repo using a command such as:

• You can also convert an individual addon with --addon-dir (instead of --addons-dir) with a command like this: