diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index cab1b7971783..f60615612f78 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -507,6 +507,102 @@ 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 and style guidelines when writing the manual. + +Use your best judgement. If you can write more clearly by breaking one of these +guidelines, please do! But remember that the guidelines exist for a reason. + +.. note:: In many cases, the manual does not follow these guidelines. If you are + already making changes to a paragraph or section of the docs, update it to + follow these standards. Avoid making unrelated changes that *only* update style, + since every change will require the paragraph to be re-translated. + +Text styles +~~~~~~~~~~~ + +There are a few styles that the manual uses. + ++---------------------+--------------------------+------------------------------------------------------------------------+ +| Style | RST formatting | Typical usage | ++=====================+==========================+========================================================================+ +| Plaintext | ``Plaintext`` | Used for most text. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| *Italics* | ``*Italics*`` | Used for emphasis. Used for introducing new terms. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| **Bold** | ``**Bold**`` | Used for emphasis, and for editor UI like menus and windows. | +| | | | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| ``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. | ++---------------------+--------------------------+------------------------------------------------------------------------+ +| "Quotes" | ``"Quotes"`` | Used for some literal or quoted values. In many cases, another | +| | | style is preferred. | ++---------------------+--------------------------+------------------------------------------------------------------------+ + + +Literals +~~~~~~~~ + +Use ``code style`` for literal values. Literals include: + +- Integer or ``int`` literals like ``0``, ``-2``, or ``100`` +- Float literals like ``0.0``, ``0.5``, ``-2.0``, or ``100.0`` +- Vector literals like ``(0.0, 0.0)``, ``(0.5, -0.5, 0.5)``, or ``(1.0, 2.0, 3.0, 4.0)``. + +Classes, properties, and methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Link to classes the first time that you mention them in a page. After the first +mention, use ``code style``. For common classes, like ``Node``, ``Control``, or +``Viewport``, you can also use plaintext. + +Link to class members (properties, methods, enums, and constants) the first time +that you mention them in a page. After the first mention, use ``code style``. If +the class member is very common, like a Node2D's ``position``, you don't have to +link. + +When discussing properties in the context of the inspector, use **Bold style** +instead. + +Editor UI +~~~~~~~~~ + +Use **bold style** for editor UI, including window titles, menus, buttons, input +fields, inspector properties, and inspector sections. Use the exact +capitalization that the editor uses. + +- Open the **Editor Settings** window. +- Press the **Confirm** button. +- Change the node's **Transform > Position** property to ``(0, 0)``. +- In the **Project Settings** window, enable the **Advanced Settings** toggle. + +Use **Bold > With > Separators** when describing sequence of menus that the +reader must navigate. Use ``>`` as a separator. You can omit ellipses in menu names. + +- In **Project > Project Settings > Input Map**, add a new input action. +- Select **Scene > Export As... > MeshLibrary...**. +- Select **Scene > Export As > MeshLibrary**. + +.. note:: Sometimes, ```->`` or ``→`` is used as a separator. This is nonstandard. + Replace it with ``>`` if you are already making changes to a section. + +Project settings +~~~~~~~~~~~~~~~~ + +Link to individual project settings. Either include the section and subsection +in the link itself, or include the section and subsection separately from the +link. Since long links are not split into multiple lines when the page is +rendered, prefer splitting the setting name and the section when the link is long. + +- Set the :ref:`Application > Run > Max FPS` setting to ``60``. +- In the project settings under **Application > Run**, set :ref:`Max FPS` to ``60``. +- In **Project Settings > Application > Run**, set :ref:`Max FPS` to ``60``. + When to refer to a specific Godot version -----------------------------------------