Comments (6)
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.
from maintainer-tools.
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.
from maintainer-tools.
@sbidoul : Here is the issue for the proposal of the new Read Me section
from maintainer-tools.
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
from maintainer-tools.
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.
from maintainer-tools.
I propose #576 to implement this.
from maintainer-tools.
Related Issues (20)
- About squashing translation commits HOT 2
- Update our tooling to support Odoo 17 HOT 20
- Mention `odoo-module-migrator` in migration procedure wiki page HOT 1
- Mention `oca-port` in migration procedure wiki page HOT 6
- oca-gen-addon-readme: exits with no error if `description.rst` is not present HOT 14
- Update migration v17 Wiki HOT 2
- Clarify CONTRIBUTOR.md formatting HOT 20
- Wiki migration 17.0: New Settings format HOT 1
- oca-gen-addon-readme: stop emitting an XML declaration HOT 1
- Fail to run pre-commit on OCA project: ERROR No matching distribution found for setuptools_scm HOT 2
- Update wiki "Migration to version 16.0" with `fields_view_get` becomes `get_view` HOT 2
- Mention data-hotkey in the 15.0 migration guide
- delete
- WIKI for documentation HOT 6
- module 'github3' has no attribute 'authorize'
- copy_maintainers script fails syncing the big teams HOT 7
- [17.0][mig] partner_statement: Migration to 17.0 HOT 1
- pandoc-3.2-1-amd64.deb added by precommit hook HOT 5
- Update command in the migration section for wiki "Migration to version 17.0". HOT 2
- Migration to version 17.0 project/project_template
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from maintainer-tools.