[IMP] contributing/documentation: update documentation guidelines

task-3709518

closes odoo/documentation#11023

X-original-commit: 9225abb13f
Signed-off-by: Audrey Vandromme (auva) <auva@odoo.com>

content/contributing/check_mergeability_status.rst

@@ -1 +0,0 @@
-At the bottom of the page, check the mergeability status and address any issues.

content/contributing/configure_git_authorship.rst

@@ -1,7 +0,0 @@
-Configure Git to identify yourself as the author of your future contributions. Enter the same email
-address you used to register on GitHub.
-
-.. code-block:: console
-
-   $ git config --global user.name "Your Name"
-   $ git config --global user.email "youremail@example.com"

content/contributing/configure_github_account.rst

@@ -1,2 +0,0 @@
-`Generate a new SSH key and register it on your GitHub account
-<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.

content/contributing/create_github_account.rst

@@ -1,3 +0,0 @@
-First, you need to `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage
-the source code of its products, and this is where you will make your changes and submit them for
-review.

content/contributing/development.rst

@@ -28,15 +28,25 @@ The instructions below help you prepare your environment for making local change
 and then push them to GitHub. Skip this section and go to
 :ref:`contributing/development/first-contribution` if you have already completed this step.
 
-#. .. include:: create_github_account.rst
+#. First, you need to `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to
-#. .. include:: configure_github_account.rst
+   manage the source code of its products, and this is where you will make your changes and submit
+   them for review.
+#. `Generate a new SSH key and register it on your GitHub account
+   <https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
 #. Go to `github.com/odoo/odoo <https://github.com/odoo/odoo>`_ and click on the :guilabel:`Fork`
    button in the top right corner to create a fork (:dfn:`your own copy`) of the repository on your
    account. Do the same with `github.com/odoo/enterprise <https://github.com/odoo/enterprise>`_ if
    you have access to it. This creates a copy of the codebase to which you can make changes without
    affecting the main codebase. Skip this step if you work at Odoo.
 #. .. include:: install_git.rst
-#. .. include:: configure_git_authorship.rst
+#. Configure Git to identify yourself as the author of your future contributions. Enter the same
+   email address you used to register on GitHub.
+
+   .. code-block:: console
+
+      $ git config --global user.name "Your Name"
+      $ git config --global user.email "youremail@example.com"
+
 #. :doc:`Install Odoo from the sources <../administration/on_premise/source>`. Make sure to fetch
    the sources through Git with SSH.
 #. Configure Git to push changes to your fork(s) rather than to the main codebase. If you work at
@@ -155,7 +165,10 @@ navigate to the directory where you installed Odoo from sources and follow the g
    #. Tick the :guilabel:`Allow edits from maintainer` checkbox. Skip this step if you work at Odoo.
    #. Complete the description and click on the :guilabel:`Create pull request` button again.
 
-#. .. include:: check_mergeability_status.rst
+#. At the bottom of the page, check the mergeability status and address any issues.
-#. .. include:: handle_reviews.rst
+#. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team
+   is automatically assigned for review. If the reviewer has questions or remarks, they will
+   post them as comments and you will be notified by email. Those comments must be resolved
+   for the contribution to go forward.
 #. Once your changes are approved, the review merges them and they become available for all Odoo
    users after the next code update!

content/contributing/documentation.rst

@@ -8,29 +8,26 @@ Documentation
    :titlesonly:
 
    documentation/content_guidelines
-   documentation/rst_cheat_sheet
    documentation/rst_guidelines
 
-This introductory guide will help you acquire the tools and knowledge you need to write
+This introductory guide will help you acquire the tools and knowledge needed to contribute to the
-documentation, whether you plan to make a minor content change or document an application from
+documentation.
-scratch.
+
+Read the :ref:`introduction to the reStructuredText language <contributing/documentation/rst-intro>`
+if you are not familiar with it. Then, there are two courses of action to start contributing to the
+documentation:
+
+- **For minor changes**, such as adding a paragraph or fixing a typo, we recommend **using the
+  GitHub interface**. This is the easiest and fastest way to submit changes, and it is suitable for
+  non-technical people. Jump directly to the :ref:`contributing/documentation/first-contribution`
+  section to get started.
+- **For more complex changes**, such as adding a new page, it is necessary to **use Git** and work
+  from a local copy of the documentation. Follow the instructions in the
+  :ref:`contributing/documentation/setup` section first to prepare your environment.
 
 .. seealso::
    :doc:`Discover other ways to contribute to Odoo <../contributing>`
 
-Read the :ref:`introduction to the reStructuredText language <contributing/documentation/rst-intro>`
-if you are not familiar with it. Then, you have two courses of action to start contributing to the
-documentation, depending on whether you want to propose minor changes to existing content or you
-instead want to work on significant changes to new and existing content.
-
-- **For minor changes**, for example, adding a paragraph or fixing a typo, we recommend **using the
-  GitHub interface**. This is the easiest and fastest way to submit your changes, and it is suitable
-  for non-technical people. Jump directly to the
-  :ref:`contributing/documentation/first-contribution` section to get started.
-- **For more complex changes**, it is necessary to **use Git** and work from a local copy of the
-  documentation. Follow the instructions in the :ref:`contributing/documentation/setup` section to
-  first prepare your environment.
-
 .. _contributing/documentation/rst-intro:
 
 reStructuredText (RST)
@@ -38,24 +35,13 @@ reStructuredText (RST)
 
 The documentation is written in **reStructuredText** (RST), a `lightweight markup language
 <https://en.wikipedia.org/wiki/Lightweight_markup_language>`_ consisting of regular text augmented
-with markup, which allows including headings, images, notes, and so on. This might seem a bit
+with markup, which allows including headings, images, notes, and so on. :abbr:`RST
-abstract, but there is no need to worry; :abbr:`RST (reStructuredText)` is not hard to learn,
+(reStructuredText)` is easy to use, even if you are not familiar with it.
-especially if you intend to make minor changes to the content.
-
-If you need to learn about a specific markup, head over to our :doc:`cheat sheet for RST
-<documentation/rst_cheat_sheet>`; it contains all the information you should ever need for the
-documentation of Odoo.
 
 .. important::
-   We kindly ask you to observe a set of :doc:`content <documentation/content_guidelines>` and
+   Be mindful of our :doc:`content <documentation/content_guidelines>` and
    :doc:`RST <documentation/rst_guidelines>` guidelines as you write documentation. This ensures
-   that you stay consistent with the rest of the documentation and facilitates the approval of your
+   that the documentation stays consistent and facilitates the approval of changes by the Odoo team.
-   content changes as the Odoo team reviews them.
-
-.. seealso::
-   - :doc:`documentation/content_guidelines`
-   - :doc:`documentation/rst_cheat_sheet`
-   - :doc:`documentation/rst_guidelines`
 
 .. _contributing/documentation/setup:
 
@@ -67,14 +53,23 @@ documentation and then push them to GitHub. Skip this section and go to
 :ref:`contributing/documentation/first-contribution` if you have already completed this step or want
 to make changes from the GitHub interface.
 
-#. .. include:: create_github_account.rst
+#. First, `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage the
-#. .. include:: configure_github_account.rst
+   source code of its products, and this is where you will submit your changes.
+#. `Generate a new SSH key and register it on your GitHub account
+   <https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
 #. Go to `github.com/odoo/documentation <https://github.com/odoo/documentation>`_ and click on the
    :guilabel:`Fork` button in the top right corner to create a fork (:dfn:`your own copy`) of the
    repository on your account. This creates a copy of the codebase to which you can make changes
    without affecting the main codebase. Skip this step if you work at Odoo.
 #. .. include:: install_git.rst
-#. .. include:: configure_git_authorship.rst
+#. Configure Git to identify yourself as the author of your future contributions. Enter the same
+   email address you used to register on GitHub.
+
+   .. code-block:: console
+
+      $ git config --global user.name "Your Name"
+      $ git config --global user.email "youremail@example.com"
+
 #. Clone the sources with Git and navigate into the local repository.
 
    .. code-block:: console
@@ -109,7 +104,7 @@ to make changes from the GitHub interface.
             $ git config commit.template %CD%\commit_template.txt
 
 #. Install the latest release of `Python <https://wiki.python.org/moin/BeginnersGuide/Download>`_
-   and `pip <https://pip.pypa.io/en/stable/installation/>`_ on your machine.
+   and `pip <https://pip.pypa.io/en/stable/installation/>`_.
 #. Install the Python dependencies of the documentation with pip.
 
    .. code-block:: console
@@ -149,18 +144,20 @@ to make changes from the GitHub interface.
          <https://www.technewstoday.com/install-and-use-make-in-windows>`_.
 
 #. `Install pngquant <https://pngquant.org/>`_.
-#. That's it! You are ready to :ref:`make your first contribution
+#. You are now ready to :ref:`make your first contribution
    <contributing/documentation/first-contribution>` with Git.
 
 .. _contributing/documentation/first-contribution:
 
-Make your first contribution
+Contributing to the documentation
-============================
+=================================
 
 .. tabs::
 
    .. tab:: Contribute from the GitHub interface
-      #. .. include:: create_github_account.rst
+
+      #. First, `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage the
+         source code of its products, and this is where you will submit your changes.
       #. Verify that you are browsing the documentation in the version that you intend to change.
          The version can be selected from the dropdown in the top menu.
       #. Head to the page that you want to change and click on the :guilabel:`Edit on GitHub` button
@@ -194,9 +191,14 @@ Make your first contribution
          Odoo.
       #. Review the summary that you wrote about your changes and click on the :guilabel:`Create
          pull request` button again.
-      #. .. include:: check_mergeability_status.rst
+      #. At the bottom of the page, check the mergeability status and address any issues.
-      #. .. include:: handle_reviews.rst
+      #. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team
-      #. .. include:: documentation/changes_approved.rst
+         is automatically assigned for review. If the reviewer has questions or remarks, they will
+         post them as comments and you will be notified by email. Those comments must be resolved
+         for the contribution to go forward.
+
+      #. Once your changes are approved, the reviewer merges them and they appear online the next
+         day.
 
    .. tab:: Contribute with Git
 
@@ -230,7 +232,7 @@ Make your first contribution
       #. Make the desired changes while taking care of following the :doc:`content
          <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>`
          guidelines.
-      #. Compress all PNG images that you added or modified.
+      #. Compress all PNG images that were added or modified.
 
          .. code-block:: console
 
@@ -239,9 +241,9 @@ Make your first contribution
 
       #. Write a `redirect rule
          <https://github.com/odoo/documentation/tree/{BRANCH}/redirects/MANUAL.md>`_ for every RST
-         file that your renamed.
+         file that were renamed.
-      #. Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in your
+      #. Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in a web
-         web browser to browse the documentation with your changes.
+         browser to browse the documentation with your changes.
 
          .. tip::
             Use :command:`make help` to learn about other useful commands.
@@ -254,7 +256,7 @@ Make your first contribution
             $ git add .
             $ git commit
 
-      #. Push your change to your fork, for which we added the remote alias `dev`.
+      #. Push your changes to your fork, for which we added the remote alias `dev`.
 
          .. example::
 
@@ -285,6 +287,10 @@ Make your first contribution
             Odoo.
          #. Complete the description and click on the :guilabel:`Create pull request` button again.
 
-      #. .. include:: check_mergeability_status.rst
+      #. At the bottom of the page, check the mergeability status and address any issues.
-      #. .. include:: handle_reviews.rst
+      #. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team
-      #. .. include:: documentation/changes_approved.rst
+         is automatically assigned for review. If the reviewer has questions or remarks, they will
+         post them as comments and you will be notified by email. Those comments must be resolved
+         for the contribution to go forward.
+      #. Once your changes are approved, the reviewer merges them and they appear online the next
+         day.

content/contributing/documentation/changes_approved.rst

@@ -1 +0,0 @@
-Once your changes are approved, the reviewer merges them and they appear online the next day!

content/contributing/documentation/content_guidelines.rst

@@ -2,228 +2,294 @@
 Content guidelines
 ==================
 
-To give the community the best documentation possible, we listed here a few guidelines, tips and
+While we encourage you to adopt your own writing style, some rules still apply to maintain clarity
-tricks that will make your content shine at its brightest! While we encourage you to adopt your own
+and ensure readers can easily understand the content.
-writing style, some rules still apply to give the reader more clarity and comprehension.
+
+.. important::
+   We strongly recommend to read the :doc:`rst_guidelines` and the main :doc:`../documentation`
+   pages before contributing.
+
+.. _contributing/content/organization:
+
+Documentation organization
+==========================
+
+When writing documentation about a given topic, keep pages within the same folder organized.
+
+For most topics, a single page should do the job. Place it in the appropriate section of the
+documentation (e.g., content related to the CRM app goes under :menuselection:`User Docs --> Sales
+--> CRM`) and follow the :ref:`document structure <contributing/content/structure>` guidelines.
+
+For more complex topics, several pages may be needed to cover all their aspects. Usually, you will
+find yourself adding documentation to a topic that is already partially covered. In that case,
+either create a new page and place it at the same level as other related pages or add new sections
+to an existing page. When documenting a complex topic from scratch, organize the content across
+several child pages that are referenced on that directory's parent page (the :abbr:`TOC (Table Of
+Contents)` page); whenever possible, write content on the parent page and not only on the child
+pages. Make the parent page accessible from the navigation menu by using the
+:ref:`show-content <contributing/rst/document-metadata>` metadata directive.
 
 .. note::
-   We strongly recommend contributors to carefully read the other documents related to this section
+   Avoid duplicating content whenever possible; if a topic is already documented on another page,
-   of the documentation. Good knowledge of the ins and outs of **RST writing** is required to write
+   :ref:`reference <contributing/rst/hyperlinks>` that existing information instead of repeating it.
-   and submit your contribution. Note that it also affects your writing style itself.
 
-   - :doc:`../documentation`
+.. important::
-   - :doc:`rst_cheat_sheet`
+   When deleting or moving a `.rst` file, update the corresponding text file in the
-   - :doc:`rst_guidelines`
+   :file:`redirects` folder based on your branch's version (e.g., :file:`17.0.txt`). To do so, add a
+   new line at the bottom of the relevant section (e.g., `# applications/sales`). On this line,
+   first, add the redirection entry point with the old file location, followed by a space, and then
+   add the exit point with the new or relevant file location. For example, if moving the file
+   :file:`unsplash.rst` from :file:`applications/websites/website/configuration` to
+   :file:`applications/general/integrations`, add the following entry under the section
+   `# applications/websites`:
 
-.. _contributing/writing-style:
+   .. code-block:: text
+
+      applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst
+
+.. _contributing/content/structure:
+
+Document structure
+==================
+
+Use different **heading levels** to organize text by sections and sub-sections. Headings are not
+only displayed in the document but also on the navigation menu (only the H1) and on the "On this
+page" sidebar (all H2 to H6).
+
++---------------------------------------------------------------------------------------+
+| | **H1: Page title**                                                                  |
+| | The *page title* gives readers a quick and clear understanding of what the content  |
+|   is about.                                                                           |
+|                                                                                       |
+| The *content* in this section describes the upcoming content from a **business point  |
+| of view**, and should not put the emphasis on Odoo, as this is documentation and not  |
+| marketing.                                                                            |
+|                                                                                       |
+| Under the page title (H1), start 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)**                                         |
+|     | | This first H2 section is about the configuration of the feature, or the       |
+|     |   prerequisites to achieve a specific goal.                                     |
++-----+---------------------------------------------------------------------------------+
+|     | | **H2: Section title (main sections)**                                         |
+|     | | Create as many main sections as you have actions or features to distinguish.  |
++-----+-----+---------------------------------------------------------------------------+
+|     |     | | **H3: Subsection**                                                      |
+|     |     | | Subsections are perfect for assessing very specific points.             |
++-----+-----+---------------------------------------------------------------------------+
+|     | **H2: Next Section**                                                            |
++-----+---------------------------------------------------------------------------------+
+
+To write good titles and headings:
+
+- **Be concise**: **avoid sentences**, questions, and titles starting with "how to".
+- **Do not use pronouns** in your titles, especially 2nd person (*you/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.).
+
+.. 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 do not entail a proper noun.
+   - Verbs in headings are fine since they often describe an action.
+
+.. seealso::
+   - :ref:`RST cheat sheet: headings <contributing/rst/headings>`
+   - :ref:`RST cheat sheet: markups <contributing/rst/markups>`
+
+.. _contributing/content/writing-style:
 
 Writing style
 =============
 
-**Writing for documentation** isn't the same as writing for a blog or another medium. Readers are
+Writing for documentation is not the same as writing for a blog or another medium. Readers are
-more likely to skim read until they've found the information they are looking for. Keep in mind that
+more likely to skim through content to find the information they need. Keep in mind that the
-the user documentation is a place to inform and describe, not to convince and promote.
+documentation is a place to **inform and describe**, not to convince and promote.
 
-.. _contributing/consistency:
+.. tip::
+   Avoid using *you* as much as possible by opting for the imperative mood where appropriate.
+   However, do not complicate sentences just to avoid addressing the reader directly.
+
+   .. example::
+      | **Good example:**
+      | Select the appropriate option from the dropdown menu.
+
+      | **Bad example:**
+      | You can select the appropriate option from the dropdown menu.
+
+.. _contributing/content/spelling:
+
+Spelling
+--------
+
+Use American English spelling and grammar throughout the documentation.
+
+.. _contributing/content/consistency:
 
 Consistency
 -----------
 
 *Consistency is key to everything.*
 
-Make sure that your writing style remains **consistent**. If you modify an existing text, try to
+Make sure that the writing style remains **consistent**. When modifying existing content, try to
-match the existing tone and presentation, or rewrite it to match your own style.
+match the existing tone and presentation or rewrite it to match your own style.
 
-.. _contributing/grammatical-tenses:
+.. _contributing/content/capitalization:
+
+Capitalization
+--------------
+
+- Use sentence case in :ref:`titles <contributing/content/structure>`.
+- Capitalize app names, e.g., **Odoo Sales**, the **Sales** app, etc.
+- Capitalize labels (such as fields and buttons) as they appear in Odoo. If a label is in all caps,
+  convert it to sentence case.
+- Capitalize the first letter after a colon if it is a complete sentence.
+- Avoid capitalizing common nouns, such as "sales order" and "bill of materials", unless you
+  reference a label or a model.
+
+.. _contributing/content/grammatical-tenses:
 
 Grammatical tenses
 ------------------
 
-In English, descriptions and instructions require the use of a **Present Tense**, while a *future
+In English, descriptions and instructions usually require the use of the **present tense**, while
-tense* is appropriate only when a specific event is to happen ulteriorly. This logic might be
+the *future tense* is appropriate only when a specific event is to happen ulteriorly.
-different in other languages.
-
-- | Good example (present):
-  | *Screenshots are automatically resized to fit the content block's width.*
-- | Bad example (future):
-  | *When you take a screenshot, remember that it will be automatically resized to fit the content
-     block's width.*
-
-.. _contributing/paragraphing:
-
-Paragraphing
-------------
-
-A paragraph comprises several sentences that are linked by a shared idea. They usually are two to
-six lines long.
-
-In English, a new idea implies a new paragraph, rather than having a *line break* as it is common to
-do in some other languages. *Line breaks* are useful for layout purposes but shouldn't be used as a
-grammatical way of separating ideas.
-
-.. seealso::
-   - :ref:`RST cheat sheet: Break the line but not the paragraph <contributing/line-break>`
-
-.. _contributing/titles:
-
-Titles and headings
--------------------
-
-To write good titles and headings:
-
-- **Be concise.**
-
-  - **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.)
-
-.. 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.
 
 .. example::
-   - **Titles** (H1)
 
-     - Quotation templates
+  | **Good example (present):**
-     - Lead mining
+  | Screenshots are automatically resized to fit the content block's width.
-     - 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)
+  | **Bad example (future):**
+  | When you take a screenshot, remember that it will be automatically resized to fit the content
+    block's width.
 
-     - Project stages
+.. _contributing/content/lists:
-     - Email alias
-     - Confirm the quotation
-     - Generate SEPA Direct Debit XML files to submit payments
 
-.. _contributing/document-structure:
+Lists
+=====
 
-Document structure
+Lists help organize information in a clear and concise manner and improve readability. They are
-==================
+used to highlight important details, guide the reader through steps in a systematic way, etc.
 
-Use different **heading levels** to organize your text by sections and sub-sections. Your headings
+Use numbered lists when the sequence matters, e.g., instructions, procedures, or steps that must be
-are not only displayed in the document but also on the navigation menu (only the H1) and on the
+performed in a particular order.
-"On this page" sidebar (all H2 to H6).
 
-+---------------------------------------------------------------------------------------+
+Use bulleted lists when the sequence of items does not matter, e.g., lists of features, fields,
-| | **H1: Page title**                                                                  |
+options, etc.
-| | Your *page title* gives your reader a quick and clear understanding of what your    |
+
-|   content is about.                                                                   |
+.. tip::
-|                                                                                       |
+   - Use inline text for explanations or when there are three or fewer list items.
-| The *content* in this section describes the upcoming content from a **business point  |
+   - Combine bulleted and numbered lists using :ref:`nested lists <contributing/rst/nested-list>`
-| of view**, and shouldn't put the emphasis on Odoo, as this is documentation and not   |
+     where appropriate.
-| marketing.                                                                            |
+   - Consider grouping simple steps within the same list item, e.g.: Go to :menuselection:`Website
-|                                                                                       |
+     --> Site --> Pages` and click :guilabel:`New`.
-| Start first with a **lead paragraph**, which helps the reader make sure that they've  |
+   - Only use a period at the end of the list item if it forms a complete sentence.
-| found the right page, then explain the **business aspects of this topic** in the      |
+
-| following paragraphs.                                                                 |
+.. example::
-+-----+---------------------------------------------------------------------------------+
+   **Bulleted list**
-|     | | **H2: Section title (configuration)**                                         |
+
-|     | | This first H2 section is about the configuration of the feature, or the       |
+   The following fields are available on the :guilabel:`Replenishment` report:
-|     |   prerequisites to achieve a specific goal. To add a path, make sure you        |
+
-|     |   use the ``:menuselection:`` specialized directive (see link below).           |
+   - :guilabel:`Product`: the product that requires a replenishment
-|     |                                                                                 |
+   - :guilabel:`Location`: the specific location where the product is stored
-|     | | Example:                                                                      |
+   - :guilabel:`Warehouse`: the warehouse where the product is stored
-|     | | To do so, go to ``:menuselection:`App name --> Menu --> Sub-menu```, and      |
+   - :guilabel:`On Hand`: the amount of product currently available
-|     |   enable the XYZ feature.                                                       |
+
-+-----+---------------------------------------------------------------------------------+
+   **Numbered list**
-|     | | **H2: Section title (main sections)**                                         |
+
-|     | | Create as many main sections as you have actions or features to distinguish.  |
+   To create a new website page, proceed as follows:
-|     |   The title can start with a verb, but try to avoid using "Create ...".         |
+
-+-----+-----+---------------------------------------------------------------------------+
+   #. - Either open the **Website** app, click :guilabel:`+ New` in the top-right corner, then
-|     |     | | **H3: Subsection**                                                      |
+        select :guilabel:`Page`;
-|     |     | | Subsections are perfect for assessing very specific points. The title   |
+      - Or go to :menuselection:`Website --> Site --> Pages` and click :guilabel:`New`.
-|     |     |   can be in the form of a question, if appropriate.                       |
+
-+-----+-----+---------------------------------------------------------------------------+
+   #. Enter a :guilabel:`Page Title`; this title is used in the menu and the page's URL.
-|     | **H2: Next Section**                                                            |
+   #. Click :guilabel:`Create`.
-+-----+---------------------------------------------------------------------------------+
+   #. Customize the page's content and appearance using the website builder, then click
+      :guilabel:`Save`.
 
 .. seealso::
-   - :ref:`RST cheat sheet: headings <contributing/headings>`
+   :ref:`RST cheat sheet: lists <contributing/rst/lists>`
-   - :ref:`RST cheat sheet: markups <contributing/markups>`
 
-.. _contributing/organizing-documentation:
+Icons
+=====
 
-Organizing the documentation
+Use :ref:`icons <contributing/rst/icons>` in instructions to help readers identify user interface
-============================
+elements and reduce the need for lengthy explanations. Accompany every icon with a descriptor
+in brackets.
 
-When writing documentation about a given topic, try to keep pages within the same folder organized.
+.. example::
+   Once the developer mode is activated, the developer tools can be accessed by clicking the
+   :icon:`fa-bug` (:guilabel:`bug`) icon.
 
-For most topics, a single page should do the job. Place it in the appropriate section of the
+.. seealso::
-documentation (e.g., content related to the CRM app go under :menuselection:`Applications
+   :ref:`RST cheat sheet: icons <contributing/rst/icons>`
--> Sales -> CRM`) and follow the :ref:`document structure <contributing/document-structure>`
-guidelines.
 
-For more complex topics, you may need several pages to cover all their aspects. Usually, you will
+.. _contributing/content/images:
-find yourself adding documentation to a topic that is already partially covered. In that case,
-either create a new page and place it at the same level as other related pages or add new sections
-to an existing page. If you are documenting a complex topic from scratch, organize your content
-between one parent page (the :abbr:`TOC (Tree Of Contents)` page) and several child pages. Whenever
-possible, write content on the parent page and not only on the child pages. Make the parent page
-accessible from the navigation menu by using the :ref:`show-content
-<contributing/document-metadata>` metadata directive.
-
-.. _contributing/content-images:
 
 Images
 ======
 
-Adding a few images to illustrate your text helps the readers to understand and memorize your
+Adding a few images to illustrate text helps the readers understand and memorize the content.
-content. However, avoid adding too many images: it isn't necessary to illustrate all steps and
+However, images should never replace text: written instructions should be complete and clear on
-features, and it may overload your page.
+their own, without relying on visual aids. Use images sparingly, for example, to highlight a
+particular point or clarify an example.
 
 .. important::
-   Don't forget to :ref:`compress your PNG files with pngquant
+   Do not forget to `compress your PNG files with pngquant <https://pngquant.org>`_.
-   <contributing/documentation/first-contribution>`.
 
-.. _contributing/screenshots:
+.. _contributing/content/screenshots:
 
 Screenshots
 -----------
 
-Screenshots are automatically resized to fit the content block's width. This implies that
+Screenshots are automatically resized to fit the content block's width. This implies that if they
-screenshots can't be too wide, else they would appear very small on-screen. Therefore, we recommend
+are too wide, they are not readable on lower-resolution screens. We recommend avoiding full-screen
-to avoid to take screenshots of a full screen display of the app, unless it is relevant to do so.
+screenshots of the app unless absolutely necessary and making sure images are no wider than a range
+of 768-933 pixels.
 
-A few tips to improve your screenshots:
+Here are a few tips to improve your screenshots:
 
-#. **Zoom** in your browser. We recommend a 110% zoom for better results.
 #. **Resize** your browser's width, either by *resizing the window* itself or by opening the
-   *browser's developer tools* (press the ``F12`` key) and resizing the width.
+   *browser's developer tools* and resizing the width.
-#. **Select** the relevant area, rather than keeping the full window.
+#. **Select** the relevant area rather than keeping the entire window.
-#. If necessary, you can **edit** the screenshot to remove unnecessary fields and to narrow even
+#. **Remove** unnecessary information and **resize** columns when applicable.
-   more Odoo's display.
 
-.. image:: content_guidelines/screenshot-tips.gif
+.. important::
-   :align: center
+   Do not use markups such as rectangles or arrows on screenshots. Instead, crop the image to
-   :alt: Three tips to take good screenshots for the Odoo documentation.
+   highlight the most relevant information, and ensure that text instructions are clear and
+   self-explanatory without relying on images.
 
-.. note::
+.. example::
-   Resizing the window's width is the most important step to do as Odoo's responsive design
+   **Good example (resized browser, no unnecessary columns, adjusted columns' width, cropped):**
-   automatically resizes all fields to match the window's width.
 
-.. _contributing/media-files:
+   .. image:: content_guidelines/quotations-list-reduced.png
+      :alt: Cropped screenshot
+
+   **Bad example (full-width screenshot):**
+
+   .. image:: content_guidelines/quotations-list-full.png
+      :alt: Full-width screenshot
+
+.. _contributing/content/media-files:
 
 Media files
 -----------
 
 A **media filename**:
 
-- is written in **lower-case letters**
+- is written in **lower-case letters**;
-- is **relevant** to the media's content. (E.g., :file:`screenshot-tips.gif`.)
+- 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`.)
+- 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
+Each RST file has its own folder for storing media files. The folder's name must be the same as the
-same as the document's filename.
+RST file's name.
 
 For example, the document :file:`doc_filename.rst` refers to two images that are placed in the
 folder ``doc_filename``.
@@ -238,12 +304,12 @@ folder ``doc_filename``.
 
 .. 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
+   placed in a single :file:`media` folder. While it is advised not to name your *new* images in
-   fashion, it is also essential **not to rename unchanged files**, as doing this would double the
+   that fashion, it is also essential **not to rename unchanged files**, as doing this would double
-   weight of renamed image files on the repository. They will eventually all be replaced as the
+   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:
+.. _contributing/content/alt-tags:
 
 ALT tags
 --------
@@ -251,14 +317,22 @@ ALT tags
 An **ALT tag** is a *text alternative* to an image. This text is displayed if the browser fails to
 render the image. It is also helpful for users who are visually impaired. Finally, it helps
 search engines, such as Google, to understand what the image is about and index it correctly, which
-improves the :abbr:`SEO (Search Engine Optimization)` significantly.
+improves :abbr:`SEO (Search Engine Optimization)`.
 
 Good ALT tags are:
 
-- **Short** (one line maximum)
+- **Short** (one line maximum);
-- **Not a repetition** of a previous sentence or title
+- **Not a repetition** of a previous sentence or title;
-- A **good description** of the action happening on the image
+- A **good description** of the action happening in the image;
-- Easily **understandable** if read aloud
+- Easily **understandable** if read aloud.
+
+.. example::
+
+   An appropriate ALT tag for the following screenshot would be *Activating the developer mode in
+   the Settings app*.
+
+   .. image:: content_guidelines/settings.png
+      :alt: Activating the developer mode in the Settings app
 
 .. seealso::
-   - :ref:`RST cheat sheet: image directive <contributing/image>`
+   :ref:`RST cheat sheet: images <contributing/rst/images>`

content/contributing/handle_reviews.rst

@@ -1,4 +0,0 @@
-As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team will be
-automatically assigned for review. If the reviewer has questions or remarks, they will post them as
-comments and you will be notified by email. Those comments must be resolved for the contribution to
-go forward.

redirects/15.0.txt

@@ -185,6 +185,10 @@ applications/websites/website/reporting/google_analytics_dashboard.rst applicati
 applications/websites/website/configuration/on-premise_geo-ip-installation.rst administration/on_premise/geo_ip.rst
 applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst                                # websites/website/configuration/ -> general/integrations/*
 
+# contributing/documentation
+
+contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst
+
 # developer/howtos
 
 developer/howtos/rdtraining/D_mixins.rst developer/tutorials/mixins.rst      # reorganize the developer doc

redirects/16.0.txt

@@ -185,6 +185,10 @@ applications/websites/website/optimize/plausible.rst applications/websites/websi
 applications/websites/website/reporting/google_analytics.rst applications/websites/website/reporting/analytics.rst                               # merged plausible.rst and google_analytics.rst
 applications/websites/website/reporting/plausible.rst applications/websites/website/reporting/analytics.rst                                      # merged plausible.rst and google_analytics.rst
 
+# contributing/documentation
+
+contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst
+
 # developer/howtos
 
 developer/howtos/discover_js_framework.rst developer/tutorials/discover_js_framework.rst                                                              # reorganize the developer doc

redirects/17.0.txt

@@ -118,3 +118,7 @@ applications/websites/ecommerce/managing_products/cross_upselling.rst applicatio
 
 applications/finance/accounting/get_started/vat_units.rst applications/finance/accounting/get_started/tax_units.rst                                        # vat_units --> tax_units
 applications/finance/accounting/taxes/taxcloud.rst applications/finance/accounting/taxes.rst                                                             # taxcloud --> taxes
+
+# contributing/documentation
+
+contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst

redirects/saas-17.2.txt

@@ -0,0 +1,3 @@
+# contributing/documentation
+
+contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst

redirects/saas-17.4.txt

@@ -0,0 +1,3 @@
+# contributing/documentation
+
+contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst