From 2017152e9c68891f710cdc7cc8de7635fa8ee46a Mon Sep 17 00:00:00 2001 From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com> Date: Tue, 29 Oct 2024 22:10:11 -0700 Subject: [PATCH] Add docs contribution checklist page --- .../docs_contribution_checklist.rst | 71 +++++++++++++++++++ .../documentation/docs_image_guidelines.rst | 10 +++ .../documentation/docs_writing_guidelines.rst | 22 ++++++ contributing/documentation/index.rst | 1 + 4 files changed, 104 insertions(+) create mode 100644 contributing/documentation/docs_contribution_checklist.rst diff --git a/contributing/documentation/docs_contribution_checklist.rst b/contributing/documentation/docs_contribution_checklist.rst new file mode 100644 index 00000000000..ed7186a5374 --- /dev/null +++ b/contributing/documentation/docs_contribution_checklist.rst @@ -0,0 +1,71 @@ +.. _docs_contribution_checklist: + +Documentation contribution checklist +==================================== + +This page is a summary of the guidelines to follow when contributing to the +documentation. Before you press that **Create pull request** button on GitHub, +read over this list to double check if you missed anything. + +You don't need to read all the guidelines here in order to start contributing. +If you do miss something, it will be pointed out during review. However, +following the guidelines you are aware of as best you can will help speed up the +review process. + +Writing style +------------- + +:ref:`See here. ` + +- Use the active voice. +- Use precise action verbs. +- Avoid verbs that end in -ing. +- Remove unnecessary adverbs and adjectives. +- Ban these 8 words: obvious, simple, basic, easy, actual, just, clear, and however. +- Use explicit references. +- Use 's to show possession. +- Use the Oxford comma. + +Code examples +------------- + +- Use dynamic typing. :ref:`See here. ` +- Use real, practical examples. Avoid ``foo`` / ``bar`` examples. :ref:`See here. ` + +Manual style and formatting +--------------------------- + +- Use common vocabulary for the editor interface. :ref:`See here. ` +- Use ``:kbd:`` for keyboard shortcuts. :ref:`See here. ` +- Literals use ``code style``. :ref:`See here. ` +- Classes link to the class reference once, then use ``ClassName`` for the rest + of the page. + Methods and properties link to the class ref once, then use ``PropertyName`` + for the rest of the page. :ref:`See here. ` +- Editor UI, like menus, windows, and editor navigation paths, use + ``Bold Style``. :ref:`See here. ` +- Link to project settings when referencing them. :ref:`See here. ` +- Text is manually wrapped to 80-100 characters. :ref:`See here. ` +- No trailing whitespace at the end of lines. +- Most of the time, avoid mentioning a specific Godot version. :ref:`See here. ` + +Images and videos +----------------- + +- New (and updated) images are in WebP format. :ref:`See here. ` +- Editor screenshots are cropped. :ref:`See here. ` +- Images larger than 1080p or 300kb are scaled down. :ref:`See here. ` +- Outlines in images use ``fffb44`` yellow. :ref:`See here. ` +- Videos use the ``:autoplay:``, ``:loop:``, and ``:muted:`` tags. :ref:`See here. ` + +GitHub +------ + +- The PR title starts with a word like ``Fix``, ``Add``, ``Update``, + ``Clarify``, or ``Improve``. +- If the PR closes an issue, link to the issue with one of GitHub's + `keywords `__: + ``closes``, ``fixes``, or ``resolves``, in the text of the PR. +- Ideally, PR contains a single commit. However, multiple commits can be + :ref:`squashed ` later. + diff --git a/contributing/documentation/docs_image_guidelines.rst b/contributing/documentation/docs_image_guidelines.rst index 7be6c25c780..4f9100b37d0 100644 --- a/contributing/documentation/docs_image_guidelines.rst +++ b/contributing/documentation/docs_image_guidelines.rst @@ -36,6 +36,8 @@ dramatically increases file size. If you're taking screenshots on a higher resolution screen the screenshot should be scaled down. There are instructions on how to do this later on this page. +.. _doc_docs_image_guidelines_format_conversion: + Format conversion ~~~~~~~~~~~~~~~~~ @@ -59,6 +61,8 @@ it may have the ability to open an image then save it as a WebP file. GIFs should be avoided. Their compression is inefficient and they only support a 256-color palette with 1-bit transparency. +.. _doc_docs_image_guidelines_cropping: + Cropping ~~~~~~~~ @@ -94,6 +98,8 @@ If you make a mistake and overcrop don't worry, cropping is non-destructive in Krita and can be adjusted. Click on the image with your cropping tool still selected and the controls will return. +.. _doc_docs_image_guidelines_scaling_down: + Scaling down an image ~~~~~~~~~~~~~~~~~~~~~ @@ -119,6 +125,8 @@ If it's still over 300KB change to lossy compression and slowly increase the com 300KB. If this results in noticeable compression artifacts using less compression is fine, even if the file size is bigger. +.. _doc_docs_image_guidelines_outlines: + Outlines, arrows and text ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -160,6 +168,8 @@ Where ``documentation_image.webp`` would be changed to the name of the image you created. Name your images in a way that makes their meaning clear, possibly with a prefix that makes their relationship to a documentation page explicit. +.. _doc_docs_image_guidelines_videos: + Videos ------ diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index 88552f4196e..e22829b90b8 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -37,6 +37,8 @@ There are 3 rules to describe classes: See the :ref:`content guidelines ` for information on the types of documentation you can write in the official documentation. +.. _doc_docs_writing_guidelines_clear_english_rules: + 7 rules for clear English ------------------------- @@ -283,6 +285,8 @@ element of a list with more than two elements. How to write methods and classes -------------------------------- +.. _doc_docs_writing_guidelines_dynamic_typing: + Dynamic vs static typing ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -335,6 +339,8 @@ The exception is topics that explain static typing concepts to users. var choice = randi() % size return arguments[choice] +.. _doc_docs_writing_guidelines_real_world_code_example: + Use real-world code examples where appropriate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -452,6 +458,7 @@ 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]``. +.. _doc_docs_writing_guidelines_common_vocabulary: Common vocabulary to use in Godot's documentation ------------------------------------------------- @@ -487,6 +494,8 @@ class names, which you can't fold, are ``Classes`` e.g. the ``properties``. E.g. ``position`` or ``modulate color`` are both ``properties``. +.. _doc_docs_writing_guidelines_keyboard_shortcuts: + Keyboard shortcut guidelines ---------------------------- @@ -507,6 +516,7 @@ 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. +.. _doc_docs_writing_guidelines_manual_style: Manual style guidelines ----------------------- @@ -567,6 +577,8 @@ is fine too. - Godot uses *nodes* with *scripts* in a *scene tree*. - Godot uses **nodes** with **scripts** in a **scene tree**. +.. _doc_docs_writing_guidelines_literals: + Literals ~~~~~~~~ @@ -576,6 +588,8 @@ Use ``code style`` for literal values. Literals include: - 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)``. +.. _doc_docs_writing_guidelines_class_properties_methods: + Classes, properties, and methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -591,6 +605,8 @@ link. When discussing properties in the context of the inspector, use **bold style** instead. +.. _doc_docs_writing_guidelines_editor_ui: + Editor UI ~~~~~~~~~ @@ -613,6 +629,8 @@ reader must navigate. Use ``>`` as a separator. You can omit ellipses in menu na .. note:: Sometimes, ``->`` or ``→`` is used as a separator. This is nonstandard. Replace it with ``>`` if you are already making changes to a section. +.. _doc_docs_writing_guidelines_project_settings: + Project settings ~~~~~~~~~~~~~~~~ @@ -625,6 +643,8 @@ rendered, prefer splitting the setting name and the section when the link is lon - In the project settings under **Application > Run**, set :ref:`Max FPS` to ``60``. - In **Project Settings > Application > Run**, set :ref:`Max FPS` to ``60``. +.. _doc_docs_writing_guidelines_manually_wrapping_lines: + Manually wrapping lines ~~~~~~~~~~~~~~~~~~~~~~~ @@ -710,6 +730,8 @@ See the `Sphinx documentation `__ for more information. +.. _doc_docs_writing_guidelines_specific_version: + When to refer to a specific Godot version ----------------------------------------- diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index 68d8697ff62..54e23de3859 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -25,6 +25,7 @@ documentation. content_guidelines docs_writing_guidelines docs_image_guidelines + docs_contribution_checklist Writing the manual ------------------