OGRE Wiki
Support and community documentation for Ogre3D
Ogre Forums
ogre3d.org
Log in
Username:
Password:
CapsLock is on.
Remember me (for 1 year)
Log in
Home
Tutorials
Tutorials Home
Basic Tutorials
Intermediate Tutorials
Mad Marx Tutorials
In Depth Tutorials
Older Tutorials
External Tutorials
Cookbook
Cookbook Home
CodeBank
Snippets
Experiences
Ogre Articles
Libraries
Libraries Home
Alternative Languages
Assembling A Toolset
Development Tools
OGRE Libraries
List of Libraries
Tools
Tools Home
DCC Tools
DCC Tutorials
DCC Articles
DCC Resources
Assembling a production pipeline
Development
Development Home
Roadmap
Building Ogre
Installing the Ogre SDK
Setting Up An Application
Ogre Wiki Tutorial Framework
Frequently Asked Questions
Google Summer Of Code
Help Requested
Ogre Core Articles
Community
Community Home
Projects Using Ogre
Recommended Reading
Contractors
Wiki
Immediate Wiki Tasklist
Wiki Ideas
Wiki Guidelines
Article Writing Guidelines
Wiki Styles
Wiki Page Tracker
Ogre Wiki Help
Ogre Wiki Help Overview
Help - Basic Syntax
Help - Images
Help - Pages and Structures
Help - Wiki Plugins
Toolbox
Freetags
Categories
List Pages
Structures
Trackers
Statistics
Rankings
List Galleries
Ogre Lexicon
Comments
History: Article Writing Guidelines
View page
Source of version: 4
(current)
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. {maketoc} !!Licensing Any code you post is released to the Public Domain, and any documentation or articles posted are released under the [http://www.gnu.org/copyleft/fdl.html|GNU Free Documentation License 1.2]. 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: ## The Obligitory Warning ## Get your boilerplate ready ## The Meaty Part ## 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 [http://1.6.1|1.6.1] 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: (alias(Ogre Wiki:Article Writing Guidelines))
Search by Tags
Search Wiki by Freetags
Latest Changes
IDE Eclipse
FMOD SoundManager
HDRlib
Building Ogre V2 with CMake
Ogre 2.1 FAQ
Minimal Ogre Collision
Artifex Terra
OpenMB
Advanced Mogre Framework
MogreSocks
...more
Search
Find
Advanced
Search Help
Online Users
96 online users