NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Actions 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#1912

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 555ebf48d7
commit 1997788e81
38 changed files with 66 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
content/applications/finance/accounting/bank.rst
View File

@ -1,8 +1,8 @@
:nosearch:
===========
Bank & Cash
===========
=============
Bank and cash
=============
.. toctree::
:titlesonly:

2
content/applications/finance/accounting/bank/feeds.rst
View File

@ -1,7 +1,7 @@
:nosearch:
==========
Bank Feeds
Bank feeds
==========
.. toctree::

2
content/applications/finance/accounting/bank/feeds/bank_statements.rst
View File

@ -1,5 +1,5 @@
===============
Bank Statements
Bank statements
===============
Importing your bank statements in Odoo Accounting allows you to keep track of the financial

2
content/applications/finance/accounting/bank/feeds/bank_synchronization.rst
View File

@ -1,5 +1,5 @@
======================================
Bank Synchronization: Automatic Import
Bank synchronization: Automatic import
======================================
Odoo can synchronize directly with your bank institution to get all bank statements imported

2
content/applications/finance/accounting/bank/reconciliation.rst
View File

@ -1,7 +1,7 @@
:nosearch:
===================
Bank Reconciliation
Bank reconciliation
===================
.. toctree::

2
content/applications/finance/accounting/fiscal_localizations.rst
View File

@ -1,7 +1,7 @@
:nosearch:
====================
Fiscal Localizations
Fiscal localizations
====================
.. toctree::

2
content/applications/finance/accounting/fiscal_localizations/overview/fiscal_localization_packages.rst
View File

@ -1,5 +1,5 @@
============================
Fiscal Localization Packages
Fiscal localization packages
============================
**Fiscal Localization Packages** are country-specific modules that install pre-configured taxes,

2
content/applications/finance/accounting/fiscal_localizations/overview/localizations_list.rst
View File

@ -6,7 +6,7 @@ Odoo Accounting can be used in many countries out of the box by installing the a
Here is a list of all :doc:`Fiscal Localization Packages <fiscal_localization_packages>` that are
available on Odoo.
Fiscal Localization Packages available
Fiscal localization packages available
======================================
- Algeria - Accounting

2
content/applications/finance/accounting/getting_started.rst
View File

@ -1,7 +1,7 @@
:nosearch:
===============
Getting Started
Getting started
===============
.. toctree::

2
content/applications/finance/accounting/getting_started/initial_configuration.rst
View File

@ -1,7 +1,7 @@
:nosearch:
=====================
Initial Configuration
Initial configuration
=====================
.. toctree::

4
content/applications/finance/accounting/others/analytic.rst
View File

@ -1,8 +1,8 @@
:nosearch:
===========
========
Analytic
===========
========
.. toctree::
:titlesonly:

2
content/applications/finance/accounting/payables.rst
View File

@ -1,7 +1,7 @@
:nosearch:
================
Account Payables
Account payables
================
.. toctree::

2
content/applications/finance/accounting/payables/pay.rst
View File

@ -1,7 +1,7 @@
:nosearch:
===============
Vendor Payments
Vendor payments
===============
.. toctree::

2
content/applications/finance/accounting/payables/pay/check.rst
View File

@ -1,5 +1,5 @@
=============
Pay by Checks
Pay by checks
=============
Once you decide to pay a supplier bill, you can select to pay by check.

2
content/applications/finance/accounting/payables/supplier_bills.rst
View File

@ -1,7 +1,7 @@
:nosearch:
============
Vendor Bills
Vendor bills
============
.. toctree::

2
content/applications/finance/accounting/payables/supplier_bills/assets.rst
View File

@ -1,5 +1,5 @@
===================================
Non-current Assets and Fixed Assets
Non-current assets and fixed assets
===================================
**Non-current Assets**, also known as **long-term assets**, are investments that are expected to be

2
content/applications/finance/accounting/payables/supplier_bills/deferred_expenses.rst
View File

@ -1,5 +1,5 @@
=================================
Deferred Expenses and Prepayments
Deferred expenses and prepayments
=================================
**Deferred expenses** and **prepayments** (also known as **prepaid expense**), are both costs that

2
content/applications/finance/accounting/payables/supplier_bills/manage.rst
View File

@ -1,5 +1,5 @@
===================
Manage vendor Bills
Manage vendor bills
===================
The **Purchase** application allows you to manage your purchase orders,

2
content/applications/finance/accounting/payables/supplier_bills/ocr.rst
View File

@ -1,5 +1,5 @@
==============================================================
Digitize Vendor Bills with Optical Character Recognition (OCR)
Digitize vendor bills with optical character recognition (OCR)
==============================================================
Encoding bills manually can be a time-consuming task. Having a solution that allows you to digitize

2
content/applications/finance/accounting/payables/supplier_bills/purchase_receipts.rst
View File

@ -1,5 +1,5 @@
=================
Purchase Receipts
Purchase receipts
=================
**Purchase Receipts** are not invoices but rather confirmations of received payments, such as a

2
content/applications/finance/accounting/receivables.rst
View File

@ -1,7 +1,7 @@
:nosearch:
===================
Account Receivables
Account receivables
===================
.. toctree::

2
content/applications/finance/accounting/receivables/customer_invoices.rst
View File

@ -1,7 +1,7 @@
:nosearch:
=================
Customer Invoices
Customer invoices
=================
.. toctree::

2
content/applications/finance/accounting/receivables/customer_invoices/cash_rounding.rst
View File

@ -1,5 +1,5 @@
=============
Cash Rounding
Cash rounding
=============
**Cash rounding** is required when the lowest physical denomination

2
content/applications/finance/accounting/receivables/customer_invoices/credit_notes.rst
View File

@ -1,5 +1,5 @@
========================
Credit Notes and Refunds
Credit notes and refunds
========================
A **credit note**, or **credit memo**, is a document issued
to a customer that notifies them that they have been credited

2
content/applications/finance/accounting/receivables/customer_invoices/deferred_revenues.rst
View File

@ -1,5 +1,5 @@
=================
Deferred Revenues
Deferred revenues
=================
**Deferred revenues**, or **unearned revenue**, are payments made in advance by customers for

2
content/applications/finance/accounting/receivables/customer_invoices/payment_terms.rst
View File

@ -1,5 +1,5 @@
===================================
Payment Terms and Installment Plans
Payment terms and installment plans
===================================
**Payment Terms** specify all the conditions under which a sale is paid, mostly to ensure customers

2
content/applications/finance/accounting/receivables/customer_invoices/snailmail.rst
View File

@ -1,5 +1,5 @@
======================================
Send your Invoices by Post (Snailmail)
Send your invoices by post (Snailmail)
======================================
Direct mail is a great way to capture individuals’ attention at a time where inboxes are always

2
content/applications/finance/accounting/receivables/customer_payments.rst
View File

@ -1,7 +1,7 @@
:nosearch:
=================
Customer Payments
Customer payments
=================
.. toctree::

2
content/applications/finance/accounting/receivables/customer_payments/batch.rst
View File

@ -1,5 +1,5 @@
==================================================
Batch Payments: Batch Deposits (checks, cash etc.)
Batch payments: Batch deposits (checks, cash etc.)
==================================================
A **Batch Deposit** groups multiple payments in a single batch. This allows you to deposit several

2
content/applications/finance/accounting/receivables/customer_payments/batch_sdd.rst
View File

@ -1,5 +1,5 @@
=======================================
Batch Payments: SEPA Direct Debit (SDD)
Batch payments: SEPA Direct Debit (SDD)
=======================================
SEPA, the Single Euro Payments Area, is a payment-integration initiative of the European Union for

2
content/applications/finance/accounting/receivables/customer_payments/online_payment.rst
View File

@ -1,5 +1,5 @@
======================
Invoice Online Payment
Invoice online payment
======================
To make it more convenient for your customers to pay the invoices you issue, you can activate the

4
content/applications/finance/accounting/reporting.rst
View File

@ -1,8 +1,8 @@
:nosearch:
===========
=========
Reporting
===========
=========
.. toctree::
:titlesonly:

2
content/applications/finance/accounting/reporting/declarations/tax_returns.rst
View File

@ -1,5 +1,5 @@
============================
Tax Return (VAT Declaration)
Tax return (VAT declaration)
============================
Companies that are registered for **VAT (Value Added Tax)** must file a **Tax return** on a monthly

2
content/applications/finance/accounting/taxation/fiscal_year.rst
View File

@ -1,7 +1,7 @@
:nosearch:
===========
Fiscal Year
Fiscal year
===========
.. toctree::

2
content/applications/finance/accounting/taxation/taxes/default_taxes.rst
View File

@ -1,5 +1,5 @@
=============
Default Taxes
Default taxes
=============
**Default Taxes** define which :doc:`taxes <taxes>` are automatically selected when there is no

2
content/applications/finance/accounting/taxation/taxes/eu_distance_selling.rst
View File

@ -1,5 +1,5 @@
===================================
EU intra-community Distance Selling
EU intra-community distance selling
===================================
**Distance sales within the European Union** include cross-border sales of goods and services to a

2
content/applications/finance/accounting/taxation/taxes/fiscal_positions.rst
View File

@ -1,5 +1,5 @@
==========================================
Fiscal Positions (tax and account mapping)
Fiscal positions (tax and account mapping)
==========================================
Default taxes and accounts are set on products and customers to create new transactions on the fly.

54
content/contributing/documentation/content_guidelines.rst
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: