From c01a71d691bc915488270744830d717beeb86ed9 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Thu, 24 Sep 2020 19:10:20 -0600 Subject: [PATCH] Edit documentation_guidelines.rst - Start with a short sentence describing the doc's content - Link to the translation docs - Remove section about translation - Many wording edits --- .../contributing/documentation_guidelines.rst | 133 ++++++++---------- 1 file changed, 57 insertions(+), 76 deletions(-) diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index faaafe42d..0713e9b3c 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -1,88 +1,85 @@ .. _doc_documentation_guidelines: -Documentation guidelines -======================== +Contributing to the documentation +================================= -This page describes the rules to follow if you want to contribute to Godot -Engine by writing or reviewing documentation, or by translating existing -documentation. Also, have a look at README of the -`godot-docs GitHub repository `_ -and the `docs front page `_ -on what steps to follow and how to contact the docs team. +This guide explains how to contribute to Godot's documentation, be it by +writing, reviewing, or translating pages. + +.. seealso:: + + If you want to translate pages or the class reference from English to other + languages, read :ref:`doc_editor_and_docs_localization`. + +Getting started +--------------- + +To modify or create pages in the reference manual, you need to edit ``.rst`` +files in the `godot-docs GitHub repository +`_. Modifying those pages in a pull +request and triggers a rebuild of the online documentation upon merging. -How to contribute ------------------ -Creating or modifying documentation pages is mainly done via the -`godot-docs GitHub repository `_. -The HTML (or PDF and EPUB) documentation is generated from the .rst files -(reStructuredText markup language) in that repository. Modifying those pages -in a pull request and getting it merged will trigger a rebuild of the online -documentation. .. seealso:: For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. Most of what it - describes regarding the main godotengine/godot repository is - also valid for the docs repository. + refer to the :ref:`doc_pr_workflow` page. Most of what it describes + regarding the main godotengine/godot repository is also valid for + the docs repository. -The README.md file contains all the information you need to get you started, -please read it. In particular, it contains some tips and tricks and links to -reference documentation about the reStructuredText markup language. +.. warning:: The class reference's source files are in the :ref:`Godot engine + repository `. We generate the + :ref:`Godot API ` section of this documentation from them. + If you want to update the description of a class, its methods, or + properties, read :ref:`doc_updating_the_class_reference`. -.. warning:: If you want to edit the **API reference**, please note that it - should *not* be done in the godot-docs repository. Instead, you - should edit the ``doc/classes/*`` XML files of Godot's - main repository. These files are then later used to generate the - in-editor documentation as well as the API reference of the - online docs. Read more here: :ref:`doc_updating_the_class_reference`. +Editing pages online +-------------------- -The 'Edit on GitHub' link -------------------------- +You can edit the documentation online by clicking the **Edit on GitHub** link in +the top-right of every page. -If you're reading documentation on `docs.godotengine.org `_, -you'll see an **Edit on GitHub** hyperlink at the top right of the page. -Once you've created a GitHub account, you can propose changes to a page you're -reading as follows: +Doing so takes you to the GitHub text editor. You need to have a GitHub account +and to log in to use it. Once logged in, you can propose change like so: 1. Click the **Edit on GitHub** button. 2. On the GitHub page you're taken to, click the pencil icon in the top-right - corner near the **Raw**, **Blame** and **History** buttons. It has the tooltip - "Edit the file in a fork of this project". + corner near the **Raw**, **Blame**, and **History** buttons. It has the + tooltip "Edit the file in a fork of this project". -3. Complete all the edits you want to make for that page. +3. Edit the text in the text editor. -4. Summarize the changes you made in the form at the bottom of the page and - click the button labelled **Propose file change** when done. +4. At the bottom of the web page, summarize the changes you made and click the + button **Propose file change**. 5. On the following screens, click the **Create pull request** button until you - see a message like *Username wants to merge 1 commit into - godotengine:master from Username:patch-6*. + see a message like *Username wants to merge 1 commit into godotengine:master + from Username:patch-6*. -6. A reviewer will evaluate your changes and incorporate them into the docs if - they're acceptable. You might also be asked to make - modifications to your changes before they're included. +Another contributor will review your changes and merge them into the docs if +they're good. They may also make changes or ask you to do so before merging. -What makes good documentation? ------------------------------- +What is the Godot documentation +------------------------------- -Documentation should be well written in plain English, using well-formed -sentences and various levels of sections and subsections. It should be clear -and objective. Also, have a look at the :ref:`doc_docs_writing_guidelines`. +The Godot documentation is intended as a comprehensive reference manual for the +Godot game engine. It is not meant to contain step-by-step tutorials, with the +exception of two game creation tutorials in the Getting Started section. -We differentiate tutorial pages from other documentation pages by these -definitions: +We strive to write objective content in accessible and well-written English. To +contribute, you should also read: -- Tutorial: a page aiming at explaining how to use one or more concepts in - the editor or scripts in order to achieve a specific goal with a learning - purpose (e.g. "Making a simple 2d Pong game", "Applying forces to an - object"). -- Documentation: a page describing precisely one and only one concept at a - time, if possible exhaustively (e.g. the list of methods of the - Sprite class, or an overview of the input management in Godot). +- The :ref:`doc_docs_writing_guidelines`. There, you will find rules to write -You are free to write the kind of documentation you wish, as long as you -respect the following rules (and the ones on the repo). +- Tutorial: a page aiming at explaining how to use one or more concepts in the + editor or scripts in order to achieve a specific goal with a learning purpose + (e.g. "Making a simple 2d Pong game", "Applying forces to an object"). +- Documentation: a page describing precisely one and only one concept at a time, + if possible exhaustively (e.g. the list of methods of the Sprite class, or an + overview of the input management in Godot). + +You are free to write the kind of documentation you wish, as long as you respect +the following rules (and the ones on the repo). Titles ------ @@ -113,22 +110,6 @@ And this is a bad example: Only project, people and node class names should have capitalized first letter. -Translating existing pages --------------------------- - -You can help to translate the official Godot documentation on our `Hosted Weblate `_. - -.. image:: https://hosted.weblate.org/widgets/godot-engine/-/godot-docs/287x66-white.png - :alt: Translation state - :align: center - :target: https://hosted.weblate.org/engage/godot-engine/?utm_source=widget - :width: 287 - :height: 66 - -There also is the official -`Godot i18n repository `_ -where you can see when the data was last synchronized. - License -------