From 803f4d3c93b3dbf46bcaabed21d03d216bac1f63 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 24 Sep 2020 11:39:55 -0600 Subject: [PATCH 1/4] Write content guidelines --- community/contributing/content_guidelines.rst | 95 +++++++++++++++++++ community/contributing/index.rst | 1 + 2 files changed, 96 insertions(+) create mode 100644 community/contributing/content_guidelines.rst diff --git a/community/contributing/content_guidelines.rst b/community/contributing/content_guidelines.rst new file mode 100644 index 000000000..b740be705 --- /dev/null +++ b/community/contributing/content_guidelines.rst @@ -0,0 +1,95 @@ +.. _doc_content_guidelines: + +Content guidelines +================== + +This document is here to help us assess what we should include in the official +documentation. Below, you will find a couple of principles and recommendations +to write accessible content. + +We want to achieve two goals: + +1. **Empathize with our users**. We should write in a way that makes it easy for + 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. + +Guidelines and principles +------------------------- + +Below are the guidelines we should strive to follow. They are not hard rules, +though: exceptionally, a topic will require breaking one or more of these. +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 +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. + +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 +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 +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 is the purpose +of signals. + +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 +may use signals, in which case we could note that the page that introduces +signals is a pre-requisite. + +Limiting cognitive load +~~~~~~~~~~~~~~~~~~~~~~~ + +Limit the cognitive load required to read the documentation. The simpler and +more explicit language we use, the more efficient it becomes for people to +learn. You can do so by: + +1. Introducing only one new concept at a time whenever possible. +2. Using simple English, as we recommend in our writing guidelines. +3. Include one or more **concrete usage examples**. Prefer a real-world example + to abstract code like ``foobar``. + +While many persons may understand more complex language and abstract examples, +you will lose others. Also, understandable writing and practical examples +benefit everyone. + +Always make an effort to **put yourself in the users’ 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 +uses with the most straightforward language possible. + +Try to remember what you first needed to know when learning about the feature or +concept. What new terms did you need to learn? What confused you? What was the +hardest to grasp? You will want users to review your work, and we recommend you +train to explain the feature before writing about it. + +.. note:: + + This principle does not mean we have to assume no prior programming + experience throughout the documentation. Having programming foundations is a + pre-requisite to use a complex engine like Godot. Talking about variables, + functions, or classes is acceptable. But we should favor plain language over + specific terminology like "metaprogramming". If you need to use precise + terms, be sure to define them. + +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, +you could link to an intro to programming in the getting started guide or a +website that teaches math theory in the math section. diff --git a/community/contributing/index.rst b/community/contributing/index.rst index d31c62fbb..c9e6cce8a 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -11,6 +11,7 @@ Contributing bisecting_regressions code_style_guidelines bug_triage_guidelines + content_guidelines documentation_guidelines docs_writing_guidelines updating_the_class_reference From b3caa1b07e3cf09ed5b1c4962d0126606137368b Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Wed, 28 Oct 2020 12:57:55 -0600 Subject: [PATCH 2/4] Add content guidelines and other guidelines to the README --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0eb1e2466..3fc930354 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,19 @@ add-on. ## Contributing changes -**Pull Requests should use the `master` branch by default. Only make Pull Requests against other branches (e.g. `2.1` or `3.0`) if your changes only apply to that specific version of Godot.** +If you'd like to contribute to the official documentation, whether you want to improve existing pages or write a new one, we would ask you to follow our workflow and guidelines: -Though arguably less convenient to edit than a wiki, this Git repository is meant to receive pull requests to always improve the documentation, add new pages, etc. Having direct access to the source files in a revision control system is a big plus to ensure the quality of our documentation. +1. If you want to write a new page, please start by opening an issue or join the discussion on an open issue with your proposal. This ensures that your work matches our [content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) and saves both you and the reviewers' time. +2. Before writing, be sure to check out our style guides: + - [Writing style guide](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html) + - [GDScript style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_styleguide.html) if you write GDScript code. + - [C# style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/c_sharp/c_sharp_style_guide.html) if you write C# code. + +We also detail how to create new pages on the documentation [here](https://docs.godotengine.org/en/latest/community/contributing/documentation_guidelines.html). + +**Pull Requests should use the `master` branch by default. Only make Pull Requests against other branches (e.g. `3.2` or `2.1`) if your changes only apply to that version of Godot.** + +_Though less convenient to edit than a wiki, having direct access to the source files in a revision control system is a big plus to ensure the quality of our documentation._ ### Editing existing pages From e4d21bdf83bfe5e1b20d1e46975cd5f734e22fd1 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 12 Nov 2020 08:30:19 -0600 Subject: [PATCH 3/4] Edit content guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve phrasing, grammar, fix indentation Co-authored-by: Rémi Verschelde Co-authored-by: balloonpopper <5151242+balloonpopper@users.noreply.github.com> --- community/contributing/content_guidelines.rst | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/community/contributing/content_guidelines.rst b/community/contributing/content_guidelines.rst index b740be705..ddd551593 100644 --- a/community/contributing/content_guidelines.rst +++ b/community/contributing/content_guidelines.rst @@ -9,7 +9,7 @@ to write accessible content. We want to achieve two goals: -1. **Empathize with our users**. We should write in a way that makes it easy for +1. **Empathize with our users.** We should write in a way that makes it easy for 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 @@ -32,11 +32,11 @@ 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 + 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 +past that threshold, consider splitting it into two parts if possible. Limiting page size forces us to write concisely and to break large documents so they each focus on a particular problem. @@ -44,8 +44,8 @@ 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 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 is the purpose -of signals. +signals”. While a bit long, the second title makes it clear what the purpose of +signals is. 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 @@ -61,35 +61,33 @@ learn. You can do so by: 1. Introducing only one new concept at a time whenever possible. 2. Using simple English, as we recommend in our writing guidelines. -3. Include one or more **concrete usage examples**. Prefer a real-world example +3. Including one or more **concrete usage examples**. Prefer a real-world example to abstract code like ``foobar``. -While many persons may understand more complex language and abstract examples, +While many people may understand more complex language and abstract examples, you will lose others. Also, understandable writing and practical examples benefit everyone. -Always make an effort to **put yourself in the users’ shoes**. When we +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 +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 uses with the most straightforward language possible. Try to remember what you first needed to know when learning about the feature or concept. What new terms did you need to learn? What confused you? What was the hardest to grasp? You will want users to review your work, and we recommend you -train to explain the feature before writing about it. +practice explaining the feature before writing about it. .. note:: - This principle does not mean we have to assume no prior programming - experience throughout the documentation. Having programming foundations is a - pre-requisite to use a complex engine like Godot. Talking about variables, - functions, or classes is acceptable. But we should favor plain language over - specific terminology like "metaprogramming". If you need to use precise - terms, be sure to define them. + Having programming foundations is a pre-requisite to use a complex engine + like Godot. Talking about variables, functions, or classes is acceptable. + But we should favor plain language over specific terminology like + "metaprogramming". If you need to use precise terms, be sure to define them. 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, -you could link to an intro to programming in the getting started guide or a +you could link to an introduction to programming in the getting started guide, or a website that teaches math theory in the math section. From 9df8c5c383c8af8a16fa2feb201c96752cf73c1a Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 12 Nov 2020 08:57:37 -0600 Subject: [PATCH 4/4] Edit content guidelines, remove typographic marks - Removed typographic marks in the entire repo - Removed a line about why we don't use a wiki - Indented notes with 4 spaces - Addressed review comments --- README.md | 4 +-- community/contributing/content_guidelines.rst | 28 +++++++++++-------- .../step_by_step/your_first_game.rst | 2 +- tutorials/export/exporting_pcks.rst | 6 ++-- tutorials/rendering/viewports.rst | 2 +- .../scripting/c_sharp/c_sharp_features.rst | 2 +- 6 files changed, 23 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3fc930354..2bb6448a8 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ add-on. If you'd like to contribute to the official documentation, whether you want to improve existing pages or write a new one, we would ask you to follow our workflow and guidelines: -1. If you want to write a new page, please start by opening an issue or join the discussion on an open issue with your proposal. This ensures that your work matches our [content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) and saves both you and the reviewers' time. +1. If you want to write a new page, please start by opening an issue or join the discussion on an open issue with your proposal. This ensures that your work matches our [content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) and saves everyone time. 2. Before writing, be sure to check out our style guides: - [Writing style guide](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html) - [GDScript style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_styleguide.html) if you write GDScript code. @@ -29,8 +29,6 @@ We also detail how to create new pages on the documentation [here](https://docs. **Pull Requests should use the `master` branch by default. Only make Pull Requests against other branches (e.g. `3.2` or `2.1`) if your changes only apply to that version of Godot.** -_Though less convenient to edit than a wiki, having direct access to the source files in a revision control system is a big plus to ensure the quality of our documentation._ - ### Editing existing pages To edit an existing page, locate its .rst source file and open it in your favorite text editor. You can then commit the changes, push them to your fork and make a pull request. diff --git a/community/contributing/content_guidelines.rst b/community/contributing/content_guidelines.rst index ddd551593..2c40103f5 100644 --- a/community/contributing/content_guidelines.rst +++ b/community/contributing/content_guidelines.rst @@ -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. diff --git a/getting_started/step_by_step/your_first_game.rst b/getting_started/step_by_step/your_first_game.rst index 38e24b537..5342b04ec 100644 --- a/getting_started/step_by_step/your_first_game.rst +++ b/getting_started/step_by_step/your_first_game.rst @@ -573,7 +573,7 @@ Adjust the "Speed (FPS)" to ``3`` for all animations. .. image:: img/mob_animations.gif -Set the ``Playing`` property in the Inspector to “On”. +Set the ``Playing`` property in the Inspector to "On". We'll select one of these animations randomly so that the mobs will have some variety. diff --git a/tutorials/export/exporting_pcks.rst b/tutorials/export/exporting_pcks.rst index 341d6033c..154d55b80 100644 --- a/tutorials/export/exporting_pcks.rst +++ b/tutorials/export/exporting_pcks.rst @@ -55,7 +55,7 @@ Generating PCK files -------------------- In order to pack all resources of a project into a PCK file open the project -and go to Project/Export and click on “Export PCK/Zip”. Also make sure to have +and go to Project/Export and click on "Export PCK/Zip". Also make sure to have an export template selected while doing so. .. image:: img/export_pck.png @@ -91,9 +91,9 @@ Opening PCK files at runtime To import a PCK file, one uses a one-liner. Keep in mind, there is no error or exception if the import fails. Instead, one might have to create some -validation code as a layer on top. The following example expects a “mod.pck” +validation code as a layer on top. The following example expects a "mod.pck" file in the directory of the games executable. The PCK file contains a -“mod_scene.tscn” test scene in its root. +"mod_scene.tscn" test scene in its root. .. tabs:: .. code-tab:: gdscript GDScript diff --git a/tutorials/rendering/viewports.rst b/tutorials/rendering/viewports.rst index 784ee449d..3e903aec8 100644 --- a/tutorials/rendering/viewports.rst +++ b/tutorials/rendering/viewports.rst @@ -187,7 +187,7 @@ The 2D usage mode is slightly faster and uses less memory compared to the 3D one If you need to render 3D shadows in the viewport, make sure to set the viewport's *Shadow Atlas Size* property to a value higher than 0. Otherwise, shadows won't be rendered. For reference, the Project Settings define it to 4096 by default. -Godot also provides a way of customizing how everything is drawn inside :ref:`Viewports ` using “Debug Draw”. +Godot also provides a way of customizing how everything is drawn inside :ref:`Viewports ` using "Debug Draw". Debug Draw allows you to specify one of four options for how the :ref:`Viewport ` will display things drawn inside it. Debug Draw is disabled by default. diff --git a/tutorials/scripting/c_sharp/c_sharp_features.rst b/tutorials/scripting/c_sharp/c_sharp_features.rst index adf90a8f0..e6b753426 100644 --- a/tutorials/scripting/c_sharp/c_sharp_features.rst +++ b/tutorials/scripting/c_sharp/c_sharp_features.rst @@ -96,7 +96,7 @@ Declaring a signal in C# is done with the ``[Signal]`` attribute on a delegate. delegate void MySignalWithArguments(string foo, int bar); These signals can then be connected either in the editor or from code with ``Connect``. -If you want to connect a signal in the editor, you need to (re)build the project assemblies to see the new signal. This build can be manually triggered by clicking the “Build” button at the top right corner of the editor window. +If you want to connect a signal in the editor, you need to (re)build the project assemblies to see the new signal. This build can be manually triggered by clicking the "Build" button at the top right corner of the editor window. .. code-block:: csharp