1 files changed, 44 insertions, 17 deletions

diff --git a/documentation/standards.md b/documentation/standards.md
index e0c0cba83c..801efe3457 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -1,6 +1,6 @@
 # Standards for contributing to Yocto Project documentation
 
-This document attemps to standardize the way the Yocto Project
+This document attempts to standardize the way the Yocto Project
 documentation is created.
 
 It is currently a work in progress.
@@ -70,27 +70,30 @@ cannot be split without infringing syntactic rules
 or reducing readability, as well as for command output
 which should be kept unmodified.
 
-### Project names
+### File, tool and command names
 
-Project names should be capitalized in the same
-way they are on Wikipedia, in particular:
+File, tool, command and package names should be double tick-quoted.
+For example, ``` ``conf/local.conf`` ``` is preferred over
+`"conf/local.conf"`.
 
-* BitBake
-* OpenEmbedded
+### Project names
 
-There are exceptions in which such names can be used
-in lower case:
+Project names should be introduced with single quotes, to have them rendered
+with an italic font and make them easier to distinguish from command names
+(double tick-quoted) and from regular English words.
 
-* When referring to a package name
-* When referring to the corresponding command name
-* When used in a cross-reference title. Such
-  titles are usually in lower case.
+An exception is when project names appear in hyperlinks, as nested markup
+is not supported by Sphinx yet.
 
-### File, tool and command names
+Project names should also be capitalized (or not) in the same way they are on
+Wikipedia, or on their own project pages if they are not described on
+Wikipedia. If a project name isn't capitalized, it should remain so even
+at the beginning of a sentence.
 
-File, tool and command names should be double tick-quoted.
-For example, ``` ``conf/local.conf`` ``` is preferred over
-`"conf/local.conf"`.
+For example:
+
+* ``` `BitBake` ```
+* ``` `ftrace` ```
 
 ### Variables
 
@@ -106,9 +109,33 @@ or in the BitBake User Manual
 If it is not described yet, the variable should be added to the
 glossary before or in the same patch it is used, so that `:term:` can be used.
 
+### Admonitions
+
+Sphinx has predefined admonitions that can be used to highlight a bit of text or
+add a side-note to the documentation. For example:
+
+```rst
+.. note::
+
+   This is a note admonition.
+```
+
+We try to limit our usage of these admonitions to `note` and `warning`, as the
+Sphinx documentation [warns](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives)
+that most themes only style these two admonitions.
+
 ## ReStructured Text Syntax standards
 
-This section has not been filled yet
+### doc directive
+
+The [doc directive](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc)
+allows to refer to another document within yocto-docs, like:
+
+    For more information, read :doc:`/bsp-guide/index`.
+
+Note that only "absolute" paths (starting with a '/') are allowed. The root
+directory of that path is documentation/, that is, :doc:`/bsp-guide/index`
+points at documentation/bsp-guide/index.rst.
 
 ## Adding screenshots