86 lines
2.7 KiB
ReStructuredText
86 lines
2.7 KiB
ReStructuredText
.. _doc_doc_and_l10n_guidelines:
|
|
|
|
Documentation and localisation guidelines
|
|
=========================================
|
|
|
|
This page describes the rules to follow if you want to contribute Godot
|
|
Engine by writing documentation or translating existing documentation.
|
|
|
|
Contribute
|
|
----------------------
|
|
|
|
Creating/Updating a documentation page or tutorial page is done via the `github repo <https://github.com/godotengine/godot-docs>`_.
|
|
The README file contains all the information you need to get you started.
|
|
|
|
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 (and the ones on the repo).
|
|
|
|
Titles
|
|
------
|
|
|
|
Always begin pages with their title and a Sphinx reference name:
|
|
|
|
::
|
|
|
|
.. _doc_insert_your_title_here:
|
|
|
|
Insert your title here
|
|
======================
|
|
|
|
Also, avoid American CamelCase titles: title's 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
|
|
|
|
Translating existing pages
|
|
--------------------------
|
|
|
|
For the moment, only English documentation is supported. So localization is not possible right now.
|
|
But please be patient, we are working on it ;) (`see issue #4 <https://github.com/godotengine/godot-docs/issues/4>`_)
|
|
|
|
**Remember** : even if Godot aims at being accessible to everyone, English is the most frequent language for documentation.
|
|
|
|
Important changes and discussions
|
|
---------------------------------
|
|
|
|
You are welcome to correct mistakes or styles to respect these
|
|
guidelines. However, in case of important changes: Use the forum, create a new topic with a link
|
|
to the incriminated page and start discussing there about your remarks.
|
|
|
|
Licence
|
|
-------
|
|
|
|
This documentation and every page it contains is published under the terms of the
|
|
Creative Commons BY 3.0 license.
|