diff --git a/contributing/documentation/content_guidelines.rst b/contributing/documentation/content_guidelines.rst index 18185b1f4..65d2ea8ad 100644 --- a/contributing/documentation/content_guidelines.rst +++ b/contributing/documentation/content_guidelines.rst @@ -68,14 +68,48 @@ grammatical way of separating ideas. .. _contributing/titles: -Titles ------- +Titles and headings +------------------- -To write a good title : +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*) +- 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. + + +------------------+-----------------------------------+--------------------------------------------------------+ + | | 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. | + +------------------+-----------------------------------+--------------------------------------------------------+ .. _contributing/document-structure: @@ -86,7 +120,7 @@ Use different **headings levels** to organize your text by sections and sub-sect are also displayed in a dynamic *navigation bar* on the side. +---------------------------------------------------------------------------------------+ -| | **H1: Page Title** | +| | **H1: Page title** | | | Your *page title* gives your reader a quick and clear understanding of what your | | content is about. It is also referenced in the section's *table of contents*. | | | @@ -94,11 +128,11 @@ are also displayed in a dynamic *navigation bar* on the side. | of view**, and shouldn't put the emphasis on Odoo, as this is documentation and not | | marketing. | | | -| Start first with a **Lead Paragraph**, which helps the reader make sure that they've | +| Start first with a **lead paragraph**, which helps the reader make sure that they've | | found the right page, then explain the **business aspects of this topic** in the | | following paragraphs. | +-----+---------------------------------------------------------------------------------+ -| | | **H2: Section Title (configuration)** | +| | | **H2: Section title (configuration)** | | | | This first H2 section is about the configuration of the feature, or the | | | prerequisites to achieve a specific goal. To add a path, make sure you | | | use the ``:menuselection:`` specialized directive (see link below). | @@ -107,7 +141,7 @@ are also displayed in a dynamic *navigation bar* on the side. | | | To do so, go to ``:menuselection:`App name --> Menu --> Sub-menu```, and | | | enable the XYZ feature. | +-----+---------------------------------------------------------------------------------+ -| | | **H2: Section Title (main sections)** | +| | | **H2: Section title (main sections)** | | | | Create as many main sections as you have actions or features to distinguish. | | | The title can start with a verb, but try to avoid using "Create ...". | +-----+-----+---------------------------------------------------------------------------+ @@ -160,6 +194,38 @@ A few tips to improve your screenshots: Resizing the window's width is the most important step to do as Odoo's responsive design automatically resizes all fields to match the window's width. +.. _contributing/media-files: + +Media files +----------- + +A **media filename**: + +- is written in **lower-case letters** +- is **relevant** to the media's content. (E.g., :file:`screenshot-tips.gif`.) +- separates its words with a **hyphen** ``-`` (E.g., :file:`awesome-filename.png`.) + +Each document has its own folder in which the media files are located. The folder's name must be the +same as the document's filename. + +For example, the document :file:`doc_filename.rst` refers to two images that are placed in the +folder ``doc_filename``. + +:: + + ├── section + │ └── doc_filename + │ │ └── screenshot-tips.gif + │ │ └── awesome-filename.png + │ └── doc_filename.rst + +.. note:: + Previously, image filenames would mostly be named with numbers (e.g., :file:`feature01.png`) and + placed in a single ``media`` folder. While it is advised not to name your *new* images in that + fashion, it is also essential **not to rename unchanged files**, as doing this would double the + weight of renamed image files on the repository. They will eventually all be replaced as the + content referencing those images is updated. + .. _contributing/alt-tags: ALT tags diff --git a/ecommerce/maximizing_revenue/pricing.rst b/ecommerce/maximizing_revenue/pricing.rst index b4aa86155..8c0c2bfb5 100644 --- a/ecommerce/maximizing_revenue/pricing.rst +++ b/ecommerce/maximizing_revenue/pricing.rst @@ -1,29 +1,30 @@ -============================================== -How to adapt the prices to my website visitors -============================================== +================================ +Adapt prices to website visitors +================================ -This section sheds some light on pricing features of eCommerce app: +This section sheds light on pricing features found in the eCommerce app: * force a price by geo-localization, * let the customer choose the currency. -As a pre-requisite, check out how to managing produt pricing: +As a pre-requisite, check out how to managing product pricing: :doc:`../../sales/products_prices/prices/pricing`). -Geo-IP to automatically apply the right price -================================================ +Geo-IP automatically applies the right price +============================================ -Assign country groups to your pricelists. That way, your visitors not yet -logged in will get their own currency when landing on your website. +Assign country groups to your pricelists. That way, visitors who aren't +logged in yet will get their own currency when landing on your website. Once logged in, they get the pricelist matching their country. Currency selector ================= -In case you sell in several currencies, you can let your customers choose -their own currency. Check *Selectable* to add the pricelist to the website drop-down menu. +In the case that you sell in several currencies, you can let your customers choose +their own. Check the *Selectable* box to add the pricelist to the website drop-down menu, which +can be found in *Pricelists* under the *Products* menu, located in the Website application. .. image:: ./media/website_pricelist_select.png :align: center diff --git a/sales/products_prices/products/import.rst b/sales/products_prices/products/import.rst index 41d10a2c3..b9b428a2b 100644 --- a/sales/products_prices/products/import.rst +++ b/sales/products_prices/products/import.rst @@ -1,43 +1,43 @@ =================================================== -How to import products with categories and variants +How to import Products with Categories and Variants =================================================== -Import templates are provided in the import tool of the most common data to +Import templates are provided in the **Import Tool** of the most common data to import (contacts, products, bank statements, etc.). -You can open them with any spreadsheets software (Microsoft Office, +You can open them with any spreadsheet software (Microsoft Office, OpenOffice, Google Drive, etc.). How to customize the file ========================= -* Remove columns you don't need. We advise to not remove the *ID* one (see - why here below). +* Remove columns you don't need. However, we advise you to not remove the *ID* column (see + why below). * Set a unique ID to every single record by dragging down the ID sequencing. -* Don't change labels of columns you want to import. Otherwise Odoo won't recognize - them anymore and you will have to map them on your own in the import screen. -* To add new columns,Feel free to add new columns but the fields need to exist in Odoo. If Odoo fails - in matching the column name with a field, you can make it manually when importing +* Don't change the labels of columns you want to import. Otherwise, Odoo won't recognize + them anymore, and you will have to map them on your own in the import screen. +* Feel free to add new columns, but the fields need to exist in Odoo. If Odoo fails + in matching the column name with a field, you can match it manually when importing by browsing a list of available fields. -Why an “ID” column -================== +Why an “ID” column? +=================== -The ID is an unique identifier for the line item. Feel free to use the one of your -previous software to ease the transition to Odoo. +The ID is a truly unique identifier for the line item. Feel free to use one of your +previous software to ease the transition into Odoo. -Setting an ID is not mandatory when importing but it helps in many cases: +Setting an ID is not mandatory when importing, but it helps in many cases: -* Update imports: you can import the same file several times without creating duplicates; +* Update imports: you can import the same file several times without creating duplicates. * Import relation fields (see here below). How to import relation fields ============================= -An Odoo object is always related to many other objects (e.g. a product is linked -to product categories, attributes, vendors, etc.). To import those relations you need to +An Odoo object is always related to many other objects (e.g., a product is linked +to product categories, attributes, vendors, etc.). To import those relations, you need to import the records of the related object first from their own list menu. -You can do it using either the name of the related record or its ID. The ID is expected when -two records have the same name. In such a case add " / ID" at the end of the column title -(e.g. for product attributes: Product Attributes / Attribute / ID). +You can do this using the name of the related record or its ID. The ID is expected when +two records have the same name. In such a case, add " / ID" at the end of the column title +(e.g., for product attributes: Product Attributes / Attribute / ID).