diff --git a/contributing/documentation.rst b/contributing/documentation.rst index e91e241a9..2c33101da 100644 --- a/contributing/documentation.rst +++ b/contributing/documentation.rst @@ -9,4 +9,5 @@ Contributing to the documentation documentation/introduction_guide documentation/rst_cheat_sheet - documentation/guidelines \ No newline at end of file + documentation/rst_guidelines + documentation/content_guidelines \ No newline at end of file diff --git a/contributing/documentation/content_guidelines.rst b/contributing/documentation/content_guidelines.rst new file mode 100644 index 000000000..18185b1f4 --- /dev/null +++ b/contributing/documentation/content_guidelines.rst @@ -0,0 +1,181 @@ +:banner: banners/contributing.png + +================== +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/titles: + +Titles +------ + +To write a good title : + +- **Be concise.** +- **Avoid sentences**, questions, and titles starting with "how to." +- **Don't use pronouns** in your titles, especially 2nd person (*your*) + +.. _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 ` + - :ref:`RST cheat sheet: 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/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/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 ` \ No newline at end of file diff --git a/contributing/documentation/introduction_guide.rst b/contributing/documentation/introduction_guide.rst index cadac2cb3..2e871866f 100644 --- a/contributing/documentation/introduction_guide.rst +++ b/contributing/documentation/introduction_guide.rst @@ -32,13 +32,15 @@ If you need to learn about a specific markup, head over to :doc:`our cheat sheet documentation of Odoo. .. important:: - We kindly ask you to observe a set of :doc:`guidelines ` as you write :abbr:`RST - (reStructuredText)`. This ensures that you stay consistent with the rest of the documentation and - facilitates the approval of your content changes as they are reviewed by a redactor at Odoo. + We kindly ask you to observe a set of :doc:`content ` and :doc:`RST + ` guidelines as you write documentation. This ensures that you stay consistent + with the rest of the documentation and facilitates the approval of your content changes as they + are reviewed by a redactor at Odoo. .. seealso:: - :doc:`rst_cheat_sheet` - - :doc:`guidelines` + - :doc:`rst_guidelines` + - :doc:`content_guidelines` .. _contributing/getting-started: @@ -81,7 +83,8 @@ Use the GitHub interface .. image:: media/fork-repository.png -#. Make the appropriate changes while taking care of following the :doc:`guidelines `. +#. Make the appropriate changes while taking care of following the :doc:`guidelines + `. #. Click on the **Preview changes** button to review your contribution in a more human-readable format. Be aware that the preview is not able to handle all markups correctly. Notes and tips, @@ -307,7 +310,7 @@ Perform your changes You can now perform any change you want to the documentation files. These changes must be compliant with :abbr:`RST (reStructuredText)` syntax (see :doc:`rst_cheat_sheet`) and with our -:doc:`guidelines `. +:doc:`guidelines `. .. important:: If your changes include the addition of a new image, for instance :file:`my_image.png`, proceed diff --git a/contributing/documentation/media/screenshot-max-width.png b/contributing/documentation/media/screenshot-max-width.png new file mode 100644 index 000000000..912aac521 Binary files /dev/null and b/contributing/documentation/media/screenshot-max-width.png differ diff --git a/contributing/documentation/media/screenshot-tips.gif b/contributing/documentation/media/screenshot-tips.gif new file mode 100644 index 000000000..c113e2daa Binary files /dev/null and b/contributing/documentation/media/screenshot-tips.gif differ diff --git a/contributing/documentation/guidelines.rst b/contributing/documentation/rst_guidelines.rst similarity index 99% rename from contributing/documentation/guidelines.rst rename to contributing/documentation/rst_guidelines.rst index 6e890126e..9c37303a7 100644 --- a/contributing/documentation/guidelines.rst +++ b/contributing/documentation/rst_guidelines.rst @@ -1,8 +1,8 @@ :banner: banners/contributing.png -========== -Guidelines -========== +============== +RST guidelines +============== .. _contributing/relative-links: diff --git a/redirects.txt b/redirects.txt index 0c20d127e..8b8544f89 100644 --- a/redirects.txt +++ b/redirects.txt @@ -24,4 +24,6 @@ # no matter the version. The section's only purpose is to help with the triage. # Consider indicating the reference of the PR (#123) that made a rule necessary, if any. -# Redirections introduced in 11.0 : \ No newline at end of file +# Redirections introduced in 11.0 : + +contributing/documentation/guidelines.rst contributing/documentation/rst_guidelines.rst # guidelines --> rst_guidelines \ No newline at end of file