Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
gdevelop5:community:contribute-to-the-wiki [2019/07/26 18:28]
4ian created
gdevelop5:community:contribute-to-the-wiki [2019/09/05 20:33] (current)
4ian [Ordering of sections]
Line 1: Line 1:
 # Contribute to the Wiki (style guide) # Contribute to the Wiki (style guide)
  
-You're welcome to improve existing pages, fix typo or write new documentation - thank you for considering ​doing it! To keep a good quality documentation,​ please ​make sure to follow these simple rules.+You're welcome to improve existing pages, fix typos or write new documentation - thank you for doing it! To ensure high quality documentation,​ please follow these simple rules.
  
 ## Use Markdown syntax ## Use Markdown syntax
  
-Prefer to use [[https://​github.com/​adam-p/​markdown-here/​wiki/​Markdown-Cheatsheet|Markdown syntax]] ​as much as possible. Not everything is supported, but as possible ​use Markdown to allow the wiki to be ported to another wiki system in the future.+The use of [[https://​github.com/​adam-p/​markdown-here/​wiki/​Markdown-Cheatsheet|Markdown syntax]] ​is preferred. Not everything is supported, but use Markdown ​whenever possible ​to allow the wiki to be ported to another wiki system in the future.
  
 Notably: Notably:
Line 19: Line 19:
 * Use Markdown backticks ​ for code/​expressions:​ `MyObject.Variable(Life)` * Use Markdown backticks ​ for code/​expressions:​ `MyObject.Variable(Life)`
  
-Similarly, avoid fancy wiki extensions like WRAP. They exist but should be avoided because not standard. ​+Avoid fancy wiki extensions like WRAP. They existbut should be avoided because ​they are not standard. ​ 
 Adding `<​note>​` is fine and encouraged though. Adding `<​note>​` is fine and encouraged though.
 +## When to use bold, italic and quotes?
 +
 +* To refer to element of the interface, prefer the quotes. Example: click on "Add an object"​.
 +* Bold is for **very important things** (details not to be forgotten). Use italic for emphasising some part of a sentence without being as visual as bold - so for things that are _less important_.
 +* For expressions/​mathematical formula or code, use the backticks: `Object.X() + 3`.
  
 ## Ordering of sections ## Ordering of sections
  
 * Keep "​Example"​ at the end of a page. * Keep "​Example"​ at the end of a page.
-* The first section must be the top and be a Level 1 Header: `# This is the title`+* The first section must be at the top and be a Level 1 Header: `# This is the title`
  
 ## Keep it concise and professional ## Keep it concise and professional
  
-The documentation is used by everyone, from kids to professional game developers. Keep concise ​writing ​in the reference pages. It'​s ​ok to refer to the reader by "​you" ​or "​we"​ in tutorials, but in other page avoid refering to the reader.+The documentation is used by everyone, from kids to professional game developers. Keep your writing ​concise ​and direct ​in the reference pages, and aim for a friendly, professional tone. It'​s ​OK to refer to the reader by "​you",​ but avoid the use of "​we"​. You're not doing the work for the reader, after all.
  
 For example: For example:
  
-instead ​of "So a Text object is as the name implies something that you can use to display a text on the screen. GDevelop even allows you to change the font. the size and tons of effects!"​ +**Instead ​of:** "So a Text object is as the name implies something that you can use to display a text on the screen. GDevelop even allows you to change the font. the size and tons of effects! ​And you can also use events to make some changes on properties." 
-prefer writing: "Text objects ​are displaying a text on the screen. ​Font, size and other effects ​can be customized."+ 
 +**Write:** "Text objects ​display ​text on screen. ​You can customize text properties (for example, size and colour) upon creation. You can also modify text object properties during gameplay using events."​ 
 + 
 +### Tips for naming the sections 💡 
 + 
 +We recommend the use of *gerunds* (verbs ending with "​ing"​ as a subject) whenever possible for headings. Usually people go to the wiki because they’re wondering “How do I…?” By ensuring wiki subheadings are in the form of gerunds, it will be easier for someone to find what they’re after... even if they don’t know exactly what it’s called within GDevelop. 
 + 
 +#### Header example #1: 
 +  * A wiki section was titled **"Joints"​**. If someone new to game creation read that header, it would mean very little to them. What does a joint do? When would they ever need to read that section? 
 +  * Changing the heading to a task-based gerund: **"​Controlling object movement with joints"​** helps the reader quickly understand what a given topic will be about. 
 + 
 +#### Header example #2 
 +  * Original header: **Admob**  
 +  * Better header: **"​Integrating ads using Google Admob"​** 
 + 
 +## Distinguish between a tutorial, a guide, and a reference page 
 + 
 +A **tutorial** provides detailed instructions for beginners in simple game creation, with step-by-step screenshots and explanations. A **guide** focuses on one specific task, and is more advanced and shorter than a tutorial. These can be found in [[gdevelop5:​tutorials|Tutorials and Guides]]. 
 + 
 +Almost everything else in the wiki is a **reference page**. A reference page should explain a concept or a feature, and give the reader a solid understanding of where and how they would use it. Assume the reader has already completed the tutorials and that they understand the basic game making concepts when writing a reference page, and only explain what is new. 
 + 
 +For example, avoid explaining how to add an object in a page about a specific type of object. People reading these help pages will already have added objects. They want to know what this specific object is used for and why, not how to add it on the screen. 
 + 
 +Similarly, in specific object pages, avoid explaining things that are common to all objects, like rotating the object. ​ This should be [[http://​wiki.compilgames.net/​doku.php/​gdevelop5/​objects/​base_object|part of this common page]].
  
-## Make the distinction between a reference page and a tutorial 
  
-A tutorial is explaining the detailed instructions about how to do something, with lots of screenshots and explanations. Tutorials are inside the "​Tutorials And Guides"​ section. +*Use your judgement. It's fine to add more in-depth explanationsGIFsor screenshots for complex features - in particular when related to extensions (PhysicsTweenetc...).
-* Almost everything else in the wiki is a reference page. It may contain a quick introduction ​to the concept, but should avoid using the tone of a tutorial and be more concise. +
-  * For example, avoid explaining how to add an object ​in the page of an object. People reading these help pages will already have added objects. They want to know about this objectnot about how to add it on the screenwhich is explained ​in all tutorials. +
-  * Similarlyin object pagesavoid explaining things that are common to all objects, like rotating the object. ​ This should be [[http://​wiki.compilgames.net/doku.php/​gdevelop5/​objects/​base_object|part of this common page]].+
  
-<note tip>You may be asking: "Sure but a bit of redundant explanations are useful no?"​. ​While it's true, it should take the form of links to other pages. Redundant explanations across the wiki make the articles harder to maintain when the software evolves - and the documentation is the most important asset after the software itself.</​note>​+<note tip>You may be asking: "Surebut does extra explanation really hurt?"​. ​Nobut it should take the form of links to other pages whenever possible. Redundant explanations across the wiki make the articles harder to maintain when the software evolves - and the documentation is the most important asset after the software itself.</​note>​
  
-## Triple check grammar and mistakes+## Triple check for grammar and mistakes
  
-A page full of mistakes and typos will have a negative ​impact ​on readers, ​that will think of GDevelop ​as something of bad quality and unreliable.+A page full of mistakes and typos will leave a negative ​impression ​on readers. If the documentation is unreliable or poorly thought outpeople may assume the same for GDevelop.
  
-Proofread multiple times what you're writingPrefer ​short sentences ​to longer ones.+  * Proofread ​your writing ​multiple times. ​ 
 +  * Use short sentences ​over longer ones.  
 +  * Remember that plain language is always best, and use correct terminology
  
 +By following this guide, we can build consistent, professional documentation for the GDevelop community.