Merge pull request #10170 from tetrapod00/contribution-checklist

Add docs contribution checklist page

Author: skyace65

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. <doc_docs_writing_guidelines_clear_english_rules>`
+
+- 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. <doc_docs_writing_guidelines_dynamic_typing>`
+- Use real, practical examples. Avoid ``foo`` / ``bar`` examples. :ref:`See here. <doc_docs_writing_guidelines_real_world_code_example>`
+
+Manual style and formatting
+---------------------------
+
+- Use common vocabulary for the editor interface. :ref:`See here. <doc_docs_writing_guidelines_common_vocabulary>`
+- Use ``:kbd:`` for keyboard shortcuts. :ref:`See here. <doc_docs_writing_guidelines_keyboard_shortcuts>`
+- Literals use ``code style``. :ref:`See here. <doc_docs_writing_guidelines_literals>`
+- 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. <doc_docs_writing_guidelines_class_properties_methods>`
+- Editor UI, like menus, windows, and editor navigation paths, use
+  ``Bold Style``. :ref:`See here. <doc_docs_writing_guidelines_editor_ui>`
+- Link to project settings when referencing them. :ref:`See here. <doc_docs_writing_guidelines_project_settings>`
+- Text is manually wrapped to 80-100 characters. :ref:`See here. <doc_docs_writing_guidelines_manually_wrapping_lines>`
+- No trailing whitespace at the end of lines.
+- Most of the time, avoid mentioning a specific Godot version. :ref:`See here. <doc_docs_writing_guidelines_specific_version>`
+
+Images and videos
+-----------------
+
+- New (and updated) images are in WebP format. :ref:`See here. <doc_docs_image_guidelines_format_conversion>`
+- Editor screenshots are cropped. :ref:`See here. <doc_docs_image_guidelines_cropping>`
+- Images larger than 1080p or 300kb are scaled down. :ref:`See here. <doc_docs_image_guidelines_scaling_down>`
+- Outlines in images use ``fffb44`` yellow. :ref:`See here. <doc_docs_image_guidelines_outlines>`
+- Videos use the ``:autoplay:``, ``:loop:``, and ``:muted:`` tags. :ref:`See here. <doc_docs_image_guidelines_videos>`
+
+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 <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests>`__:
+  ``closes``, ``fixes``, or ``resolves``, in the text of the PR.
+- Ideally, PR contains a single commit. However, multiple commits can be
+  :ref:`squashed <doc_pr_workflow_rebase>` later.
+

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
 ------
 

contributing/documentation/docs_writing_guidelines.rst

@@ -37,6 +37,8 @@ There are 3 rules to describe classes:
     See the :ref:`content guidelines <doc_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<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
     - In **Project Settings > Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
 
+.. _doc_docs_writing_guidelines_manually_wrapping_lines:
+
 Manually wrapping lines
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -710,6 +730,8 @@ See the `Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restru
 and the `reStructuredText documentation <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections>`__
 for more information.
 
+.. _doc_docs_writing_guidelines_specific_version:
+
 When to refer to a specific Godot version
 -----------------------------------------
 

contributing/documentation/index.rst

@@ -25,6 +25,7 @@ documentation.
    content_guidelines
    docs_writing_guidelines
    docs_image_guidelines
+   docs_contribution_checklist
 
 Writing the manual
 ------------------