Add a new CONTEXT section into README.rst

[TumbaoJu]

Add a new CONTEXT section into README.rst

[francesco-ooops]

Hi @pedrobaeza,

being "Description" the first visible part of the readme, I think it would be good if we could keep it as concise and direct as possible, explaining immediately "what" the module does;

"Usage" should then explain "how" the goal in description is achieved;

"Context/Use Cases" would be a space (also) for functionals to go in depth of the "why" one should employ this module.

IMHO it wouldn't be ideal to have too long of a "Description" section; I think @TumbaoJu request has the goal of adding a space where functionals can find and contribute module documentation without making the main description too lengthy.

[pedrobaeza]

I think the description is the best suitable place, but my opinion is only one amongst a lot, so if the rest wants to go that direction, OK for me.

[TumbaoJu]

@sbidoul : Here is the issue for the proposal of the new Read Me section

[pedrobaeza]

I'm not sure about adding a new section instead of putting the business use case inside DESCRIPTION.rst, which is the most visible one and most of the times is equivalent and the explanation is blended with the rest of the description. See for example https://github.com/OCA/sale-workflow/pull/2473/files#diff-630cc9f3ce79965b50eee70bf1e7247de551fb31fa5eafe8cd05a71e02998c34R28

[sbidoul]

Missing use case is often my main complaint concerning OCA documentation. Too often I contemplate a module, more or less understanding what it does but wondering when to use it.

So I'm in favor of encouraging contributors to add context / use case information.

I also think the description part must remain concise. I don't know if use case information would often be too long for the description section.

One interesting benefit of a separate CONTEXT fragment is that it opens the possibility to enforce its presence in 17.

[sbidoul]

I propose #576 to implement this.