mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 16:28:59 +00:00
add docs writing guidelines
- add page to the toctree - add RST formatting and blocks - add pic to the img/ folder - add convention to style arguments in class reference, like [code]this[/code]
This commit is contained in:
Nathan
@@ -0,0 +1,360 @@
|
||||
.. _doc_docs_writing_guidelines:
|
||||
|
||||
Godot docs writing guidelines
|
||||
=============================
|
||||
|
||||
The Godot community is rich and international. Users come from all
|
||||
around the world. Some of them are young, and many aren't native English
|
||||
speakers. That's why we must all write using a clear and a common
|
||||
language. For the class reference, the goal is to make it easy to read
|
||||
for everyone and precise.
|
||||
|
||||
In summary, always try to:
|
||||
|
||||
1. Use the direct voice
|
||||
2. Use precise action verbs
|
||||
3. Avoid verbs that end in -ing
|
||||
4. Remove unnecessary adverbs and adjectives.
|
||||
5. Ban these 8 words
|
||||
6. Use explicit references
|
||||
7. Use 's to show possession
|
||||
|
||||
There are 3 rules to describe classes:
|
||||
|
||||
1. Give an overview of the node in the brief description
|
||||
2. Mention what methods return if it's useful
|
||||
3. Use "if true" to describe booleans
|
||||
|
||||
.. note::
|
||||
|
||||
A technical writer's job is to pack as much information as possible into
|
||||
the smallest and clearest sentences possible. These guidelines will help
|
||||
you work towards that goal.
|
||||
|
||||
7 rules for a clear english
|
||||
---------------------------
|
||||
|
||||
|
||||
Use the direct voice
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Use the direct voice when possible. Take the classes, methods, and
|
||||
constants you describe as the subject. It's natural to write using the
|
||||
passive voice, but it's harder to read and produces longer sentences.
|
||||
|
||||
Passive:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
The man **was bitten** by the dog.
|
||||
|
||||
Active:
|
||||
|
||||
::
|
||||
|
||||
The dog bit the man.
|
||||
|
||||
|
||||
**Don't** use the passive voice:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
void edit_set_pivot ( Vector2 pivot )
|
||||
[...] This method **is implemented** only in some nodes that inherit Node2D.
|
||||
|
||||
**Do** use the node's name as a noun:
|
||||
|
||||
::
|
||||
|
||||
void edit_set_pivot ( Vector2 pivot )
|
||||
[...] Only some Node2Ds **implement** this method.
|
||||
|
||||
Use precise action verbs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Favor precise yet common verbs over generic ones like ``make``, ``set``,
|
||||
and any expression you can replace with a single word.
|
||||
|
||||
**Don't** repeat the method's name. It already states it sets the pivot
|
||||
value to a new one:
|
||||
|
||||
::
|
||||
|
||||
void edit_set_pivot ( Vector2 pivot )
|
||||
Set the pivot position of the 2D node to ‘pivot’ value. [...]
|
||||
|
||||
**Do** explain what's the consequence of this "set": use precise verbs
|
||||
like ``place``, ``position``, ``rotate``, ``fade``, etc.
|
||||
|
||||
::
|
||||
|
||||
void edit_set_pivot ( Vector2 pivot )
|
||||
Position the node's pivot to the 'pivot' value. [...]
|
||||
|
||||
Avoid verbs that end in -ing
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The progressive forms describe continuous actions. E.g. "is calling",
|
||||
"is moving".
|
||||
|
||||
**Don't** use the progressive form for instant changes.
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
Vector2 move ( Vector2 rel_vec )
|
||||
Move the body in the given direction, **stopping** if there is an obstacle. [...]
|
||||
|
||||
**Do** use simple present, preterit or future.
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
Vector2 move ( Vector2 rel_vec )
|
||||
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]
|
||||
|
||||
You may use the progressive tense to describe actions that are
|
||||
continuous in time. Anything like animation or coroutines.
|
||||
|
||||
.. tip::
|
||||
|
||||
Verbs can turn into adjectival nouns with -ing. This is not a
|
||||
conjugation, so you may use them: ``the remaining movement``,
|
||||
``the missing file``, etc.
|
||||
|
||||
Remove unnecessary adverbs and adjectives
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Write as few adjectives and adverbs as possible. Only use them if they
|
||||
add key information to the description.
|
||||
|
||||
**Don't** use redundant or meaningless adverbs. Words that lengthen the
|
||||
documentation but don't add any information:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Basically** a big texture [...]
|
||||
|
||||
**Do** write short sentences in a simple, descriptive language:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
A big texture [...]
|
||||
|
||||
Ban these 8 words
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Don't** ever use these 8 banned words:
|
||||
|
||||
1. obvious
|
||||
2. simple
|
||||
3. basic
|
||||
4. easy
|
||||
5. actual
|
||||
6. just
|
||||
7. clear
|
||||
8. however (some uses)
|
||||
|
||||
Game creation and programming aren't simple, and nothing's easy to
|
||||
someone learning to use the API for the first time. Other words in the
|
||||
list, like ``just`` or ``actual`` won't add any info to the sentence.
|
||||
Don't use corresponding adverbs either: obviously, simply, basically,
|
||||
easily, actually, clearly.
|
||||
|
||||
**Don't** example. The banned words lengthen the description and take
|
||||
attention away from the most important info:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**TextureRect**
|
||||
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.
|
||||
|
||||
**Do** remove them:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**TextureRect**
|
||||
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.
|
||||
|
||||
"Simple" never helps. Remember, for other users, anything could be
|
||||
complex or frustrate them. There's nothing like a good old *it's simple*
|
||||
to make you cringe. Here's the old brief description, the first sentence
|
||||
on the Timer node's page:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Timer**
|
||||
A **simple** Timer node.
|
||||
|
||||
**Do** explain what the node does instead:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Timer**
|
||||
Calls a function of your choice after a certain duration.
|
||||
|
||||
**Don't** use "basic", it is too vague:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Vector3**
|
||||
Vector class, which performs **basic** 3D vector math operations.
|
||||
|
||||
**Do** use the brief description to offer an overview of the node:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Vector3**
|
||||
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.
|
||||
|
||||
Use explicit references
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Favor explicit references over implicit ones.
|
||||
|
||||
**Don't** use words like "the former", "the latter", etc. They're not
|
||||
the most common in English, and they require you to check the reference.
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
'w' and 'h' define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.
|
||||
|
||||
**Do** repeat words. They remove all ambiguity:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
'w' and 'h' define right and bottom margins. **'w' and 'h'** resize the texture so it fits the margin.
|
||||
|
||||
If you need to repeat the same variable name 3 or 4 times, you probably
|
||||
need to rephrase your description.
|
||||
|
||||
Use 's to show possession
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Avoid "The milk **of** the cow". It feels unnatural in English. Write "The cow's
|
||||
milk" instead.
|
||||
|
||||
**Don't** write "of the X":
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
The region **of the AtlasTexture that is** used.
|
||||
|
||||
**Do** use ``'s``. It lets you put the main subject at the start of the
|
||||
sentence, and keep it short:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
The **AtlasTexture's** used region.
|
||||
|
||||
How to write methods and classes
|
||||
--------------------------------
|
||||
|
||||
Give an overview of the node in the brief description
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The brief description is the reference's most important sentence. It's
|
||||
the user's first contact with a node:
|
||||
|
||||
1. It's the only description in the "Create New Node" dialog.
|
||||
2. It's at the top of every page in the reference
|
||||
|
||||
The brief description should explain the node's role and its
|
||||
functionality, in up to 200 characters.
|
||||
|
||||
**Don't** write tiny and vague summaries:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Node2D**
|
||||
Base node for 2D system.
|
||||
|
||||
**Do** give an overview of the node's functionality:
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
**Node2D**
|
||||
2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.
|
||||
|
||||
Use the node's full description to provide more information, and a code
|
||||
example, if possible.
|
||||
|
||||
Mention what methods return if it's useful
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Some methods return important values. Describe them at the end of the
|
||||
description, ideally on a new line. No need to mention the return values
|
||||
for any method whose name starts with ``set`` or ``get``.
|
||||
|
||||
**Don't** use the passive voice:
|
||||
|
||||
::
|
||||
|
||||
Vector2 move ( Vector2 rel_vec )
|
||||
[...] The returned vector is how much movement was remaining before being stopped.
|
||||
|
||||
**Do** always use "Returns".
|
||||
|
||||
::
|
||||
|
||||
Vector2 move ( Vector2 rel_vec )
|
||||
[...] Returns the remaining movement before the body was stopped.
|
||||
|
||||
Notice the exception to the "direct voice" rule: with the move method,
|
||||
an external collider can influence the method and the body that calls
|
||||
``move``. In this case, you can use the passive voice.
|
||||
|
||||
Use "if true" to describe booleans
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For boolean member variables, always use ``if true`` and/or
|
||||
``if false``, to stay explicit. ``Controls whether or not`` may be
|
||||
ambiguous and won't work for every member variable.
|
||||
|
||||
Also surround boolean values, variable names and methods with [code][/code].
|
||||
|
||||
**Do** start with "if true":
|
||||
|
||||
.. highlight:: md
|
||||
|
||||
Timer.autostart
|
||||
If [code]true[/code] the timer will automatically start when it enters the scene tree. Default value: `false`.
|
||||
|
||||
|
||||
Use [code] around arguments
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In the class reference, always surround arguments with [code][/code]. In the documentation and in Godot, it will display like ``this``. When you edit XML files in the Godot repository, replace existing arguments written like 'this' or \`this\` with [code]this[/code].
|
||||
|
||||
|
||||
Common vocabulary to use in godot's docs
|
||||
----------------------------------------
|
||||
|
||||
The developers chose some specific words to refer to areas of the
|
||||
interface. They're used in the sources, in the documentation, and you
|
||||
should always use them instead of synonyms, so the users know what
|
||||
you're talking about.
|
||||
|
||||
.. figure:: img/editor-vocabulary-overview.png
|
||||
:alt: Overview of the interface and common vocabulary
|
||||
|
||||
Overview of the interface and common vocabulary
|
||||
|
||||
In the top left corner of the editor lie the ``main menus``. In the
|
||||
center, the buttons change the ``workspace``. And together the buttons
|
||||
in the top right are the ``playtest buttons``. The area in the center,
|
||||
that displays the 2D or the 3D space, is the ``viewport``. At its top,
|
||||
you find a list of ``tools`` inside the ``toolbar``.
|
||||
|
||||
The tabs or dockable panels on either side of the viewport are
|
||||
``docks``. You have the ``FileSystem dock``, the ``Scene dock`` that
|
||||
contains your scene tree, the ``Import dock``, the ``Node dock``, and
|
||||
the ``Inspector`` or ``Inspector dock``. With the default layout you may
|
||||
call the tabbed docks ``tabs``: the ``Scene tab``, the ``Node tab``...
|
||||
|
||||
The Animation, Debugger, etc. at the bottom of the viewport are
|
||||
``panels``. Together they make up the ``bottom panels``.
|
||||
|
||||
Foldable areas of the Inspector are ``sections``. The node's parent
|
||||
class names, which you can't fold, are ``Classes`` e.g. the
|
||||
``KinematicBody2D class``. And individual lines with key-value pairs are
|
||||
``properties``. E.g. ``position`` or ``modulate color`` are both
|
||||
``properties``.
|
||||
@@ -10,4 +10,5 @@ Contributing
|
||||
code_style_guidelines
|
||||
bug_triage_guidelines
|
||||
documentation_guidelines
|
||||
docs_writing_guidelines
|
||||
updating_the_class_reference
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
Reference in New Issue
Block a user