diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index cab1b7971783..8741e1ec9702 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -507,6 +507,119 @@ examples with the ``:kbd:`` tag left as-is for better visibility: - Press ``:kbd:`Space``` and hold the left mouse button to pan in the 2D editor. - Press ``:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels. + +Manual style guidelines +----------------------- + +Follow these formatting guidelines while writing documentation. Use your best judgement. +If you can write more clearly by ignoring these guidelines, do so. + +.. note:: Much of the existing manual does not follow these guidelines. You don't + have to go out of your way to change existing pages, but do try to bring + pages up to standards when you are already making changes. + +Text styles +~~~~~~~~~~~ + +There are a few styles that the manual uses. + + ++---------------------+--------------------------+------------------------------------------------------------------------+ +| Style | RST formatting | Typical usage | ++=====================+==========================+========================================================================+ +| Plaintext | ``Plaintext`` | Used for most text. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| "Quotes" | ``"Quotes"`` | Used for some literal or quoted values. In many cases, another | +| | | style is preferred. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| *Italics* | ``*Italics*`` | Used for emphasis. Used for introducing new terms. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| **Bold** | ``**Bold**`` | Used for emphasis, editor menus and windows, | +| | | and editor navigation paths. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| ``Code`` | `` Code `` | Used for variable names, literal values, and code snippets. ``code`` is| +| | | used in many cases where you would use "quoted plaintext" in typical | +| | | English. | ++---------------------+--------------------------+------------------------------------------------------------------------+ + + +Literals +~~~~~~~~ + +Literal values use ``code style``. + +- Ints: ``0``, ``2``, ``-5``, ``100``. +- Often, floats include the decimal: ``0.0``, ``0.5``, ``2.0``, ``-5.0``, ``1000.0``. +- Often, vectors include the decimal, and have a space between each field: ``(0.0, 0.0)``, ``(0.5, -0.5, 0.5)``, ``(1.0, 2.0, 3.0, 4.0)``. + +Classes, properties, and methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When discussing a class, link to the class reference the first time you mention it within a section. +After the first mention of the class, do not link to the class reference. If the class is very common, +like ``Node``, ``Node3D``, ``Control``, or ``Viewport``, you don't have to link. When discussing an instance of +a class, do not link to the class reference. + +When mentioning a class property or method, link to the class reference the first time you mention it in a section. +If the class member is very common, like a Node2D's ``position``, you don't have to link. Instead, either style as plaintext +or ``code style``. + +Properties +~~~~~~~~~~ + +Properties are styled differently, depending on whether you are using the inspector +or not. + +For properties in the inspector, use either ``code style`` or **bold style**, and +use the name it appears in the inspector. If the property is nested within the +inspector, use the full path. + +For properties being used in code example, link to the property the first time it +is mentioned, then use ``code style``. + +Editor menus and windows +~~~~~~~~~~~~~~~~~~~~~~~~ + +Editor menus and windows use **bold style**. Plaintext is also okay, if it's more natural. +For example, use **bold style** when referring specifically to **Project Settings** window, +but use plaintext when referring to the concept of project settings. + +**Good**: + +- **Editor Settings** +- The **Editor Settings** window. + +Editor navigation paths +^^^^^^^^^^^^^^^^^^^^^^^ + +Editor navigation paths are used to describe a series of menus, submenus, actions, +or buttons that the reader should follow. Navigation paths use **bold** style, +and use ``>``, ``->``, or ``→`` as a separator, with spaces on both sides. + +**Good**: + +- **Editor > Editor Settings > Shortcuts** + +**Okay**: + +- **Editor -> Editor Settings -> Shortcuts** +- **Editor → Editor Settings → Shortcuts** + +Project settings +~~~~~~~~~~~~~~~~ + +Always link to project settings. Either include the full path of the setting in +the link text, or specify the path and the link separately. The setting name +should be ``Title Case``, as it appears in the project settings. The project +setting navigation path is styled as **Bold > With > Arrows**. + +**Good**: + +- Set :ref:`Max FPS` in **Project Settings > Application > Run** to ``60``. +- In **Project Settings > Application > Run**, set :ref:`Max FPS` to ``60``. +- Set the :ref:`ProjectSettings > Application > Run Max FPS` project setting to ``60``. + + When to refer to a specific Godot version -----------------------------------------