Article Writing Guidelines         A set of guidelines that tutorial writers should adhere to in order to maintain consistent, high quality work.
Print

The Ogre community has become quite large and the availability of talent and good content is such that we can afford to hold up certain standards. Thus we have created a set of guidelines that tutorial writers should adhere to in order to maintain consistent, high quality work.

Licensing

Any code you post is released to the Public Domain, and any documentation or articles posted are released under the GNU Free Documentation License 1.2(external link). If this is not acceptable, post it on your own website and create a link in the external links section.

Conventions

Introduction

Ogre tutorials are very good in their current state, and we hope that future articles will maintain that same level of quality. The idea is that each tutorial should read like a Wikipedia article, meaning it has an obvious flow with no interruptions or asides which interfere with the tutorial. Each article should guide the user from beginning to end on a single topic (or a handful of closely related topics). To this end we have come up with a few conventions that we hope will help with this process.

PLEASE NOTE: The goal of these conventions are to create a high quality, readable tutorial for the sake of the people new to Ogre. You may break any of these conventions you like as long as you are certain that it will make the tutorial in some way better than otherwise following these rules.

Creating a Tutorial

  • For the main Ogre tutorials, name the article in the format: Level Tutorial # (ie Basic Tutorial 9)
  • Please write the OGRE version the tutorial is written or updated for.
  • Do not put your name on the tutorial. Though you may break this rule if you wish, we have found that it makes people shy about editing it, and when they do, they add notes saying "such and such doesn't work, change it to such and such -New Author's Name" instead of actually fixing it in the tutorial. This leads to highly disjoint, confusing tutorials. Write your "created by" note on the Discussion page.
  • Avoid large paragraphs. Break them up a bit.
  • Use a professional writing style. Don't get too silly in your writing. If you start warning your audience about anything or using a lot of cliches like 'just my $.02' you're bordering on silly.
  • Name sections according to content. The table of contents should show a map of where the discussion is going to go. This is an example of a bad TOC:
    1. The Obligitory Warning
    2. Get your boilerplate ready
    3. The Meaty Part
    4. From Bad to Worse
  • Write for multiple platforms. Ogre has a wide audience. If you don't use another platform ask someone in the forums to cross check your work before posting. This basically means don't use windows specific code or, if you do, include it in #ifdef WIN32 blocks. Look at Clay's tutorials for an example (i.e. Basic Tutorial 1).
  • Stay on topic. Pick one or a few related topics and write exclusively to that subject. If you have many ideas, make separate tutorials.

 

Accuracy

  • Use proper English, spelling and grammar. Copy it into Word to do a spelling & grammar check if need be.
  • Link your article with the articles or tutorials page only after it has been proof read.
  • Don't post code that you haven't actually compiled and ran, nor code that you didn't write.
  • Post all code necessary, and don't leave anything out. If you extend the -ExampleApplication framework, just post your code. Provide both the inline code that you are commenting on, and also post the full code base for easy copying and pasting.

 

Editing a Tutorial

  • Do not insert your name or into the middle of an article. Feel free to take credit for whatever you have added or fixed on the discussion page.
  • Tutorials should have an obvious flow to it. Integrate what needs to be said or fixed into the article itself without writing a side note unless what needs to be said is lengthy enough for an entirely new section.
  • If something is wrong, fix it. Do not write a side note with your name attached. If it's wrong then the original version doesn't need to be there anyway.
  • If editing a tutorial, do not write asides or notes which are disjoint from the article. Imagine each article as a Wikipedia article that explains how to do something.
  • If a tutorial has not been upgraded to the most recent version of Ogre, please upgrade it in-place. Do not add sections such as "for 1.6.1(external link) compiling..." and so on. The tutorials should always be up-to-date with the most recent version of Ogre. Since these are for people learning how to use Ogre, and new people will use the most recent version, we do not need to keep old code for earlier ogre versions around.

 

Types of Tutorials

File your tutorial in the correct place based on content and assumptions about the knowledge of the reader.

Leveled Tutorials

All leveled tutorials should build an application from beginning to end, resulting in a demoable application.

Basic Tutorials:

Beginner tutorials assume no prior knowledge of Ogre aside from the previous beginner tutorials. These tutorials should use as small of an amount of intermediate C++ concepts as well (i.e. try not to use STL containers, templates, etc). Stick to a short topic with only a very small number of related concepts to demonstrate.

Intermediate Tutorials:

Intermediate tutorials assume that the user has worked through the beginner tutorials and intermediate tutorials up to the number you are writing. Additionally they may use all C++ concepts which are required for it (STL containers, templates, and so on), but still try to limit yourself to only what is absolutely necessary for the topic in question.

Other Types

In-Depth Tutorials:

Advanced tutorials assume the user has done the previous tutorials and has used Ogre outside of the tutorials. It may use any and all C++ concepts which are appropriate for the tutorial. The resulting tutorial may span many files and many classes (some of which will probably not be explained if it is not the focus of the tutorial). However, what sets an advanced tutorial apart from an intermediate tutorial is that it should cover a single topic (or multiple related topics) either in-depth or very broadly.

Good examples of an in-depth tutorial would be creating your own scene manager (which would be very in depth), and exploring how resources are used in Ogre (very broad, covering multiple aspects of the startup process).

Older Tutorials:

These are tutorials that have fallen out of date, and no one has answered the call to update them. If a tutorial goes out of date, please update it! If you cannot or are disinterested in updating it, make a post in the General Forum to request assistance updating it. If no one does and the tutorial is no longer usable, move the link down to the older tutorial category, where (hopefully) someone will eventually update it and move it back to one of the above locations.


Alias: Ogre Wiki:Article Writing Guidelines


Contributors to this page: jacmoe180265 points  and Mikademus .
Page last modified on Sunday 10 of January, 2010 11:21:13 UTC by jacmoe180265 points .


The content on this page is licensed under the terms of the Creative Commons Attribution-ShareAlike License.
As an exception, any source code contributed within the content is released into the Public Domain.