|
@@ -13,7 +13,7 @@ We want to achieve two goals:
|
|
|
them to learn from the docs.
|
|
|
2. **Write a complete reference manual**. Our goal here is not to teach
|
|
|
programming foundations. Instead, we should provide a reference for how
|
|
|
- Godot’s features work.
|
|
|
+ Godot's features work.
|
|
|
|
|
|
Guidelines and principles
|
|
|
-------------------------
|
|
@@ -25,15 +25,15 @@ Still, we should strive to achieve the two goals listed above.
|
|
|
Writing complete and accessible documentation
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
-**A feature doesn’t exist unless it is documented**. If a user can’t find
|
|
|
-information about a feature and how it works, it doesn’t exist to them. We
|
|
|
+**A feature doesn't exist unless it is documented**. If a user can't find
|
|
|
+information about a feature and how it works, it doesn't exist to them. We
|
|
|
should ensure that we cover everything Godot does.
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
- When adding or updating an engine feature, the documentation team needs to
|
|
|
- know about it. Contributors should open an issue on the `godot-docs` repository
|
|
|
- when their work gets merged and requires documentation.
|
|
|
+ When adding or updating an engine feature, the documentation team needs to
|
|
|
+ know about it. Contributors should open an issue on the `godot-docs` repository
|
|
|
+ when their work gets merged and requires documentation.
|
|
|
|
|
|
Do your best to keep documents **under 1000 words in length**. If a page goes
|
|
|
past that threshold, consider splitting it into two parts if possible. Limiting
|
|
@@ -41,11 +41,15 @@ page size forces us to write concisely and to break large documents so they each
|
|
|
focus on a particular problem.
|
|
|
|
|
|
Make it clear what **problem** each page or section of a page tackles and what
|
|
|
-the user will learn from it. Users need to know if they’re reading the correct
|
|
|
+the user will learn from it. Users need to know if they're reading the correct
|
|
|
guide to solving problems they encounter. For example, instead of writing the
|
|
|
-heading “Signals”, consider writing “Reacting to changes in another object with
|
|
|
-signals”. While a bit long, the second title makes it clear what the purpose of
|
|
|
-signals is.
|
|
|
+heading "Signals", consider writing "Reacting to changes with signals". The
|
|
|
+second title makes it clear what the purpose of signals is.
|
|
|
+
|
|
|
+.. note::
|
|
|
+
|
|
|
+ Long section titles lead to long entries in the side menu, which can make
|
|
|
+ navigation cumbersome. Try to keep headings five words long or less.
|
|
|
|
|
|
If the page assumes specific knowledge of other Godot features, mention it and
|
|
|
link it to the corresponding documentation. For instance, a page about physics
|
|
@@ -71,7 +75,7 @@ benefit everyone.
|
|
|
Always make an effort to **put yourself in the user's shoes**. When we
|
|
|
understand something thoroughly, it becomes evident to us. We may fail to think
|
|
|
about details relevant to a newcomer, but **good documentation meets users where
|
|
|
-they are**. We should strive to explain each feature’s capabilities or intended
|
|
|
+they are**. We should strive to explain each feature's capabilities or intended
|
|
|
uses with the most straightforward language possible.
|
|
|
|
|
|
Try to remember what you first needed to know when learning about the feature or
|
|
@@ -88,6 +92,6 @@ practice explaining the feature before writing about it.
|
|
|
|
|
|
When a page assumes knowledge of another engine feature, declare it at the
|
|
|
beginning and link to resources that cover what users need. You may also link to
|
|
|
-other websites for pre-requisites beyond the documentation’s scope. For example,
|
|
|
+other websites for pre-requisites beyond the documentation's scope. For example,
|
|
|
you could link to an introduction to programming in the getting started guide, or a
|
|
|
website that teaches math theory in the math section.
|