Content guidelines

Pour donner à la communauté la meilleure documentation possible, nous avons répertorié ici quelques conseils et astuces qui feront briller votre contenu sous son meilleur jour! Bien que nous vous encourageons à adopter votre propre style d’écriture, certaines règles s’appliquent toujours pour donner au lecteur plus de clarté et de compréhension.

Note

We strongly recommend contributors to carefully read the other documents related to this 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.

Style d’écriture

Ecrire de la documentation est assez différent de la rédaction pour un blog ou un autre support. Les lecteurs sont plus susceptibles de parcourir le contenu en diagonale jusqu’à ce qu’ils aient trouvé les informations qu’ils recherchent. Gardez à l’esprit que la documentation utilisateur est un lieu pour informer et décrire, non pour convaincre et promouvoir.

Cohérence

La cohérence est la clé.

Assurez-vous que votre style d’écriture reste cohérent. Si vous modifiez un texte existant, essayez de faire correspondre le ton et la présentation, ou réécrivez-le pour qu’il corresponde à votre propre style.

Temps grammaticaux

En anglais, les descriptions et les instructions nécessitent l’utilisation du présent, tandis que le futur n’est approprié que lorsqu’un événement spécifique doit se produire ultérieurement. Cette logique peut être différente dans d’autres langues.

  • Bon exemple (présent) :
    Screenshots are automatically resized to fit the content block’s width.
  • Mauvais exemple (futur) :
    When you take a screenshot, remember that it will be automatically resized to fit the content block’s width.

Utilisation des paragraphes

Un paragraphe comprend plusieurs phrases liées par une idée partagée. Ils comportent généralement de deux à six lignes.

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.

Titles and headings

To write good titles and headings:

  • Soyez concis.

    • 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

    • 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

Document structure

Use different heading levels to organize your text by sections and sub-sections. Your 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
Your page title gives your reader a quick and clear understanding of what your content is about.

Le contenu de cette section décrit le contenu à venir d’un point de vue business, et ne doit pas mettre l’accent sur Odoo, car il s’agit de documentation et non de 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)
Cette première section H2 concerne la configuration de la fonctionnalité ou les prérequis pour atteindre un objectif spécifique. Pour ajouter un chemin, assurez-vous d’utiliser la directive spécialisée :menuselection: (voir lien ci-dessous).
Exemple :
To do so, go to :menuselection:`App name --> Menu --> Sub-menu`, and enable the XYZ feature.
H2: Section title (main sections)
Créez autant de sections principales que vous avez d’actions ou de fonctionnalités à distinguer. Le titre peut commencer par un verbe, mais essayez d’éviter d’utiliser « Créer … ».
H3 : sous-section
Les sous-sections sont parfaites pour évaluer des points très spécifiques. Le titre peut prendre la forme d’une question, le cas échéant.

H2 : Section suivante

Organizing the documentation

When writing documentation about a given topic, try to 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 go under Applications -> Sales -> CRM) and follow the document structure guidelines.

For more complex topics, you may need several pages 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. If you are documenting a complex topic from scratch, organize your content between one parent page (the TOC 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 show-content metadata directive.

Images

L’ajout de quelques images pour illustrer votre texte aide les lecteurs à comprendre et à mémoriser votre contenu. Cependant, évitez d’ajouter trop d’images : il n’est pas nécessaire d’illustrer toutes les étapes et fonctionnalités, et cela peut surcharger votre page.

Important

Don’t forget to compress your PNG files with pngquant.

Captures d’écran

Les captures d’écran sont automatiquement redimensionnées pour s’adapter à la largeur du bloc de contenu. Cela implique que les captures d’écran ne peuvent pas être trop larges, sinon elles apparaîtront très petites à l’écran. Par conséquent, nous vous recommandons d’éviter de prendre des captures d’écran d’un affichage plein écran de l’application, à moins que cela ne soit pertinent.

Quelques conseils pour améliorer vos captures d’écran :

  1. Zoomez dans votre navigateur. Nous recommandons un zoom de 110% pour de meilleurs résultats.

  2. Redimensionnez la largeur de votre navigateur, soit en redimensionnant la fenêtre elle-même, soit en ouvrant les outils de développement du navigateur (appuyez sur la touche `` F12``) et en redimensionnant la largeur.

  3. Sélectionnez la zone appropriée, plutôt que de conserver la fenêtre complète.

  4. Si nécessaire, vous pouvez modifier la capture d’écran pour supprimer les champs inutiles et affiner encore plus l’affichage d’Odoo.

Three tips to take good screenshots for the Odoo documentation.

Note

Le redimensionnement de la largeur de la fenêtre est l’étape la plus importante à réaliser car la conception réactive d’Odoo redimensionne automatiquement tous les champs pour qu’ils correspondent à la largeur de la fenêtre.

Media files

A media filename:

  • is written in lower-case letters

  • is relevant to the media’s content. (E.g., screenshot-tips.gif.)

  • separates its words with a hyphen - (E.g., 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 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., 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.

Tags ALT

Un tag ALT est une alternative textuelle à une image. Ce texte s’affiche si le navigateur ne parvient pas à afficher l’image. Il est également utile pour les utilisateurs malvoyants. Enfin, il aide les moteurs de recherche, comme Google, à comprendre en quoi consiste l’image et à l’indexer correctement, ce qui améliore considérablement le SEO.

Les bons tags ALT sont :

  • Court (une ligne maximum)

  • Pas une répétition d’une phrase ou d’un titre précédent

  • Une bonne description de l’action qui se passe sur l’image

  • Facilement compréhensible si lu à haute voix