2016-02-08 22:07:55 +01:00
|
|
|
:: _doc_doc_and_l10n_guidelines:
|
|
|
|
|
2016-02-06 01:54:33 +01:00
|
|
|
Documentation writing and translating guidelines
|
|
|
|
================================================
|
|
|
|
|
|
|
|
This page describes the rules to follow if you want to contribute Godot
|
|
|
|
Engine by writing documentation or translating existing documentation.
|
|
|
|
|
|
|
|
What is a good documentation ?
|
|
|
|
------------------------------
|
|
|
|
|
|
|
|
A good documentation is well written in plain English and well-formed
|
|
|
|
sentences. It is clear and objective.
|
|
|
|
|
|
|
|
A documentation page is not a tutorial page. We differentiate these
|
|
|
|
concepts by these definitions :
|
|
|
|
|
|
|
|
- tutorial : a page aiming at explaining how to use one or more
|
|
|
|
concepts in Godot Editor in order to achieve a specific goal with a
|
|
|
|
learning purpose (ie. "make a simple 2d Pong game", "apply forces to
|
|
|
|
an object"...)
|
|
|
|
- documentation : a page describing precisely one and only one concept
|
|
|
|
at the time, if possible exhaustively (ie. the list of methods of the
|
|
|
|
Sprite class for example).
|
|
|
|
|
|
|
|
You are free to write the kind of documentation you wish, as long as you
|
|
|
|
respect the following rules.
|
|
|
|
|
|
|
|
Create a new wiki page
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
Creating a new documentation page or tutorial page is easy. The
|
|
|
|
following rules must be respected :
|
|
|
|
|
|
|
|
- Choose a short and explicit title
|
|
|
|
- Respect the grammar and orthography
|
|
|
|
- Make use of the [[Wiki syntax]]
|
|
|
|
|
|
|
|
| Try to structure your page in order to enable users to include a page
|
|
|
|
directly in another page or even forum posts using the include wiki
|
|
|
|
syntax. For example, the syntax to include the page you are reading is
|
|
|
|
:
|
|
|
|
| !{{include(Documentation writing and translating guidelines)}}.
|
|
|
|
|
|
|
|
Titles
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
| Please always begin pages with their name:
|
|
|
|
| ``h1. <Insert your title here>``
|
|
|
|
|
|
|
|
Also, avoid American CamelCase titles: titles' first word should begin
|
|
|
|
with a capitalized letter, and every following word should not. Thus,
|
|
|
|
this is a good example:
|
|
|
|
|
|
|
|
- Insert your title here
|
|
|
|
And this is a bad example:
|
|
|
|
- Insert Your Title Here
|
|
|
|
|
|
|
|
Only project names (and people names) should have capitalized first
|
|
|
|
letter. This is good:
|
|
|
|
|
|
|
|
- Starting up with Godot Engine
|
|
|
|
and this is bad:
|
|
|
|
- Starting up with godot engine
|
|
|
|
|
|
|
|
Note for non-English authors
|
|
|
|
----------------------------
|
|
|
|
|
|
|
|
| If you intend to create a new page in your language, you are asked to
|
|
|
|
firstly create the corresponding English page if it doesn't already
|
|
|
|
exist. **Do it even if you will not write it yourself, just leave it
|
|
|
|
blank.** Only then, create the corresponding page in your own
|
|
|
|
language. Maybe later, another contributor will translate your new
|
|
|
|
page to English.
|
|
|
|
| **Remember** : even if Godot aims at being accessible to everyone,
|
|
|
|
English is the most frequent language for documentation.
|
|
|
|
|
|
|
|
Translating existing pages
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
You are very welcome to translate existing pages from English to your
|
|
|
|
language, or from your language to English. If these guidelines were
|
|
|
|
respected, an English page already exists for every page of this wiki,
|
|
|
|
even if it is empty. To translate an existing page, please follow these
|
|
|
|
few rules :
|
|
|
|
|
|
|
|
- Respect the grammar and orthography
|
|
|
|
- Make use of the [[wiki syntax]]
|
|
|
|
- Re-use images
|
|
|
|
- Always keep the structure of the English page (if it is written yet,
|
|
|
|
follow the structure of the original language page you are
|
|
|
|
translating from).
|
|
|
|
|
|
|
|
To translate an existing page, simply copy its original content. Then,
|
|
|
|
create the new page in the section of your language, copy the English
|
|
|
|
content in it and start translating.
|
|
|
|
|
|
|
|
| Please add a line at the very beginning of your translation, linking
|
|
|
|
to the English base page you translate from :
|
|
|
|
| Traduction de ![[Godot Engine:Creating 2D Games]]
|
|
|
|
|
|
|
|
The previous link is of the form ![[:]] which enables you to add a link
|
|
|
|
to a page located in an other project. Here, "Godot Engine" is the
|
|
|
|
English project.
|
|
|
|
|
|
|
|
Important changes and discussions
|
|
|
|
---------------------------------
|
|
|
|
|
|
|
|
You are welcome to correct mistakes or styles to respect these
|
|
|
|
guidelines. However, in case of important changes, please do not start a
|
|
|
|
discussion on this page : use the forum, create a new topic with a link
|
|
|
|
to the incriminated page and start discussing there about your remarks.
|
|
|
|
|
|
|
|
Licence
|
|
|
|
-------
|
|
|
|
|
|
|
|
This wiki and every page it contains is published under the terms of the
|
2016-02-07 23:59:10 +01:00
|
|
|
Creative Commons BY 3.0 license.
|