Difference between revisions of "Legacy:Guidelines On Tutorials"

Latest revision as of 15:53, 15 December 2005

These are rough guidelines for writing tutorials on the site. You might want to read New Contributors Quick Start and Wiki FAQ first.

Title[edit]

The name of a page is what is used to link with. Tutorials tend to have "procedural" names, such as "Building a Skybox" or "Using the Terrain Tool". But above all, pick a page name that will hopefully show up in searches. (though experience shows that whatever you pick, someone will type in completely different search terms and complain that they can't find it :( )

Prerequisites[edit]

You should add prerequisites to the tutorial page in order for the person to fully enjoy following through with it. They should be in bulleted format.

Class overview[edit]

A coding tutorial might give an overview of the classes created, like this:

Standard parent class >> New class 

Description.

Text[edit]

The text of your tutorial should allow the audience (another Wiki user) to follow your lead as you go from ignorance to knowledge of a useful topic.

Do[edit]

• Attempt to address your audience and their needs.
• Organize your thoughts in a logical progression.
• Build upon past knowledge and basic proceedures.
• Reach the basic goals first, reach further and beyond afterwards.

Avoid[edit]

• Avoid putting your specific ideas ahead of the audience's generalized needs.
• Avoid large blocks of text without some organized headings and subheadings.
• Avoid new ideas until the ideas they are based on are made clear.
• Avoid ranting, commentary and circular discussions.

Making it findable[edit]

Link from somewhere[edit]

The wiki is a web: it's important that pages interconnect, so you need to find a spot to link from. You'll need to create a link on at least one page to get started. It's a good idea to link from any page that is relevant.

Some place you could link from:

• one of the Topic pages that are listed in the "Encyclopedia" section on Home Page. This means your page is only two levels down the hierarchy
• the "Lessons" pages on Home Page might also be suitable
• other related tutorials
• class spec pages which are related to what you're doing. For example, if your tutorial uses Emitters, you could make a list at the foot of that page of "Tutorials which demonstrate using this actor" or something.

All this will help people find your page in the wiki (1,600 pages as of March 03!).

Tag it[edit]

Add a link to Category:Legacy Tutorial at the foot of your tutorial. This tags your page so it shows up on category searches.

Add links[edit]

There is a huge amount of material on the wiki that you can link to. Remember to link to:

• "parent" pages: the wiki is a web, so there's no knowing how someone will arrive on your page. If you write it as a child of some other page (eg "Terrain tool specifics", remember to give a link to the parent page ("Terrain tool overview" or whatever).
• related Topic pages
• related tutorials.

Class pages, basic procedure pages and interface pages will make your tutorial considerably simpler to write. Here's how:

Class pages[edit]

These give the full spec for a class. The name of a class spec page is, well, just the name of the class. Like this: xEmitter. You don't need to write an explanation of what the class is – or you can just copy what's on the class page.

Interface pages[edit]

Most of the UnrealEd Interface is documented. You don't need to explain the toolbar or the actor properties window yet again for n00bs: just link. Pages such as toolbar and texture browser will give all the details (and if you think those pages aren't good enough: improve them). When giving menu commands, use the UnrealEd Menus pages.

Basic procedures[edit]

Even better than that, simple procedures are already explained on separate pages. You don't need to explain how to add a new actor to the map: this is covered completely on Add an Actor, with screenshots, whistles and bells. The idea behind this is that tutorials are a little bit modular:

• tutorial writers don't have to keep reinventing the wheel.
• Beginners will find everything they need, and will also recognize the same procedures in different tutorials and learn them more quickly
• more advanced readers won't get bored skipping though stuff they already know.

There is a full list of these "mini tutorials" along with ideas on how to link them into your text on Category:Legacy Basic Procedure. Take a look at what is there before writing your tutorial. Feel free to improve these or add new ones.

Images[edit]

The same idea as above: don't reinvent the wheel. If an image already exists on the wiki, reuse it. Steal images from:

• Category:Legacy Basic Procedure pages
• UnrealEd Interface pages

In fact, if you find an image that already covers what you are doing, consider splitting that section off into a Basic Procedure module.

See also Images for guidelines on image names.