OCA Functional Workgroup - Documentation Project
Module Documentation

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:

$ oca-gen-addon-readme --convert-fragments-to-markdown --org-name OCA --repo-name rest-framework --branch 16.0 --addons-dir . --gen-html
  • You can also convert an individual addon with --addon-dir (instead of --addons-dir) with a command like this:

$ oca-gen-addon-readme --convert-fragments-to-markdown --org-name OCA --repo-name purchase-workflow --branch 16.0 --addon-dir purchase_request --gen-html
 

How to proceed in case of pushing a new module into OCA?

  • Using the templates (which are now in Markdown)

  • And we recommend you follow the Guidelines!

    • We will be communicating about these Guidelines when they are ready!

We hope you enjoy these improvements!!!

The OCA Functional Group, Documentation Team
Julie LeBrun, Numigi Solutions
Francesco Foresti, ooops
Lara Freeke, Therp
Benedito Monteiro

Cover Photo by Sigmund on Unsplash

OCA Functional Workgroup - Documentation Project
MoaHub, Rebecca Gellatly 28 September, 2023
Share this post
Archive
Sign in to leave a comment
Interview with Karin Broeking
Matsters Thesis: Open Source Communities