NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[IMP] contributing: modify titles and headings guidelines

Browse Source 
The previous guidelines for titles and headings included an exception to
capitalize feature names as they are written in the apps. However, this
exception seems to have confused most writers as it isn't always clear
what should be considered as a feature name or what should be considered
as a noun or noun group. This commit removes this exception to make the
writing and reviewing processes easier while retaining good titles and
improving consistency across the documentation. It also changes the
titles of the Accounting section to provide a better example to other
writers.

task-id 2843109

closes odoo/documentation#1921

X-original-commit: 1997788e81
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
Signed-off-by: Castillo Jonathan (jcs) <jcs@odoo.com>
This commit is contained in:
Jonathan Castillo (jcs)
2022-05-04 12:36:35 +00:00
parent f0ea12f515
commit 8bada22d42
38 changed files with 66 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/contributing/documentation/content_guidelines.rst
+25 -29
View File
@@ -72,42 +72,38 @@ Titles and headings
To write good titles and headings:
- **Be concise.**
- **Avoid sentences**, questions, and titles starting with "how to."
- **Don't use pronouns** in your titles, especially 2nd person (*your*)
- **Avoid sentences**, unnecessary verbs, questions, and titles starting with "how to."
- **Don't use pronouns** in your titles, especially 2nd person (*your*).
- Use **sentence case**. This means you capitalize only:
- the first word of the title or heading
- the first word after a colon
- proper nouns (brands, product and service names, etc.)
- app features, as written in the apps
.. important::
Do not capitalize common nouns when they are not referred to as features. This is more likely
to happen in headings rather than in titles.
.. note::
- Most titles and headings generally refer to a concept and do *not* represent the name of a
feature or a model.
- Do not capitalize the words of an acronym if they don't entail a proper noun.
- Verbs in headings are fine since they often describe an action.
+------------------+-----------------------------------+--------------------------------------------------------+
| | Examples | Explanations |
+==================+===================================+========================================================+
| | **Titles** | *Quotation Templates* | "Quotation Templates" is a feature in Odoo. |
| | (H1) +-----------------------------------+--------------------------------------------------------+
| | *Lead Mining* | "Lead Mining" is a feature in Odoo. |
| +-----------------------------------+--------------------------------------------------------+
| | *Resupply from another Warehouse* | "Warehouse" is capitalized as we refer to the feature |
| | | in the app rather than to a real warehouse. |
| +-----------------------------------+--------------------------------------------------------+
| | *Synchronize Google Calendar | "Google Calendar" is a product and "Odoo" is a brand. |
| | with Odoo* | |
+------------------+-----------------------------------+--------------------------------------------------------+
| | **Headings** | *Confirm the quotation* | "The quotation" is a common noun not referring to a |
| | (H2, H3, etc.) | | feature in Odoo. |
| +-----------------------------------+--------------------------------------------------------+
| | *Test environment* | "Environment" is a common noun. |
| +-----------------------------------+--------------------------------------------------------+
| | *Add a new Payment Acquirer* | "Payment Acquirers" is a feature in Odoo. |
| +-----------------------------------+--------------------------------------------------------+
| | *Generate SEPA Direct Debit XML | "SEPA Direct Debit" and "XML" are considered as proper |
| | files to submit payments* | nouns. |
+------------------+-----------------------------------+--------------------------------------------------------+
.. example::
- **Titles** (H1)
- Quotation templates
- Lead mining
- Resupply from another warehouse
- Synchronize Google Calendar with Odoo
- Batch payments: SEPA Direct Debit (SDD)
- Digitize vendor bills with optical character recognition (OCR)
- **Headings** (H2, H3)
- Project stages
- Email alias
- Confirm the quotation
- Generate SEPA Direct Debit XML files to submit payments
.. _contributing/document-structure: