e3fee2cf46
Prior to this commit, the Odoo documentation was mainly split between
two repositories: odoo/odoo/doc and odoo/documentation-user. Some bits
of documentation were also hosted elsewhere (e.g., wiki, upgrade, ...).
This was causing several problems among which:
- The theme, config, Makefile, and similar technical resources had to
be duplicated. This resulted in inconsistent layout, features, and
build environments from one documentation to another.
- Some pages did not fit either documentation as they were relevant
for both users and developers. Some were relevant to neither of the
two (e.g., DB management).
- Cross-doc references had to be absolute links and they broke often.
- Merging large image files in the developer documentation would bloat
the odoo/odoo repository. Some contributions had to be lightened to
avoid merging too many images (e.g., Odoo development tutorials).
- Long-time contributors to the user documentation were chilly about
going through the merging process of the developer documentation
because of the runbot, mergebot, `odoo-dev` repository, etc.
- Some contributors would look for the developer documentation in the
`odoo/documentation-user` repository.
- Community issues about the user documentation were submitted on the
`odoo/odoo` repository and vice-versa.
Merging all documentations in one repository will allow us to have one
place, one theme, one work process, and one set of tools (build
environment, ...) for all of the Odoo docs.
As this is a good opportunity to revamp the layout of the documentation,
a brand new theme replaces the old one. It features a new way to
navigate the documentation, centered on the idea of always letting the
reader know what is the context (enclosing section, child pages, page
structure ...) of the page they are reading. The previous theme would
quickly confuse readers as they navigated the documentation and followed
cross-application links.
The chance is also taken to get rid of all the technical dangling parts,
performance issues, and left-overs. Except for some page-specific JS
scripts, the Odoo theme Sphinx extension is re-written from scratch
based on the latest Sphinx release to benefit from the improvements and
ease future contributions.
task-2351938
task-2352371
task-2205684
task-2352544
Closes #945
246 lines
12 KiB
ReStructuredText
246 lines
12 KiB
ReStructuredText
|
|
==================
|
|
Content guidelines
|
|
==================
|
|
|
|
To give the community the best documentation possible, we listed here a few guidelines, tips and
|
|
tricks that will make your content shine at its brightest! While we encourage you to adopt your own
|
|
writing style, some rules still apply to give the reader more clarity and comprehension.
|
|
|
|
.. note::
|
|
We strongly recommend contributors to carefully read the other documents in this *Contribution*
|
|
section of the documentation. Good knowledge of the ins and outs of **RST writing** is required
|
|
to write and submit your contribution. Note that it also affects your writing style itself.
|
|
|
|
- :doc:`introduction_guide`
|
|
- :doc:`rst_cheat_sheet`
|
|
- :doc:`rst_guidelines`
|
|
|
|
.. _contributing/writing-style:
|
|
|
|
Writing style
|
|
=============
|
|
|
|
**Writing for documentation** isn't 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
|
|
the user documentation is a place to inform and describe, not to convince and promote.
|
|
|
|
.. _contributing/consistency:
|
|
|
|
Consistency
|
|
-----------
|
|
|
|
*Consistency is key to everything.*
|
|
|
|
Make sure that your writing style remains **consistent**. If you modify an existing text, try to
|
|
match the existing tone and presentation, or rewrite it to match your own style.
|
|
|
|
.. _contributing/grammatical-tenses:
|
|
|
|
Grammatical tenses
|
|
------------------
|
|
|
|
In English, descriptions and instructions require the use of a **Present Tense**, while a *future
|
|
tense* is appropriate only when a specific event is to happen ulteriorly. This logic might be
|
|
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**, 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:
|
|
|
|
Document's structure
|
|
====================
|
|
|
|
Use different **headings levels** to organize your text by sections and sub-sections. Your headings
|
|
are also displayed in a dynamic *navigation bar* on the side.
|
|
|
|
+---------------------------------------------------------------------------------------+
|
|
| | **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*. |
|
|
| |
|
|
| The *content* in this section describes the upcoming content from a **business point |
|
|
| 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 |
|
|
| 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. To add a path, make sure you |
|
|
| | use the ``:menuselection:`` specialized directive (see link below). |
|
|
| | |
|
|
| | | Example: |
|
|
| | | To do so, go to ``:menuselection:`App name --> Menu --> Sub-menu```, and |
|
|
| | enable the XYZ feature. |
|
|
+-----+---------------------------------------------------------------------------------+
|
|
| | | **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 ...". |
|
|
+-----+-----+---------------------------------------------------------------------------+
|
|
| | | | **H3: Subsection** |
|
|
| | | | Subsections are perfect for assessing very specific points. The title |
|
|
| | | can be in the form of a question, if appropriate. |
|
|
+-----+-----+---------------------------------------------------------------------------+
|
|
| | **H2: Next Section** |
|
|
+-----+---------------------------------------------------------------------------------+
|
|
|
|
.. seealso::
|
|
- :ref:`RST cheat sheet: headings <contributing/headings>`
|
|
- :ref:`RST cheat sheet: specialized directives <contributing/specialized-directives>`
|
|
|
|
.. _contributing/content-images:
|
|
|
|
Images
|
|
======
|
|
|
|
Adding a few images to illustrate your text helps the readers to understand and memorize your
|
|
content. However, avoid adding too many images: it isn't necessary to illustrate all steps and
|
|
features, and it may overload your page.
|
|
|
|
.. important::
|
|
Don't forget to :ref:`compress your PNG files with pngquant <contributing/pngquant>`.
|
|
|
|
.. _contributing/screenshots:
|
|
|
|
Screenshots
|
|
-----------
|
|
|
|
Screenshots are automatically resized to fit the content block's width. This implies that
|
|
screenshots can't be too wide, else they would appear very small on-screen. Therefore, we recommend
|
|
to avoid to take screenshots of a full screen display of the app, unless it is relevant to do so.
|
|
|
|
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.
|
|
#. **Select** the relevant area, rather than keeping the full window.
|
|
#. If necessary, you can **edit** the screenshot to remove unnecessary fields and to narrow even
|
|
more Odoo's display.
|
|
|
|
.. image:: media/screenshot-tips.gif
|
|
:align: center
|
|
:alt: Three tips to take good screenshots for the Odoo documentation.
|
|
|
|
.. note::
|
|
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
|
|
--------
|
|
|
|
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.
|
|
|
|
Good ALT tags are:
|
|
|
|
- **Short** (one line maximum)
|
|
- **Not a repetition** of a previous sentence or title
|
|
- A **good description** of the action happening on the image
|
|
- Easily **understandable** if read aloud
|
|
|
|
.. seealso::
|
|
- :ref:`RST cheat sheet: image directive <contributing/image>` |