Motorious:Style guide

From Motorious

NOTE! This style guide contains information about what should be written in articles. For help on how to edit articles by reading Help:Editing.

General guidelines

Motorious articles assume that the reader is at least slightly confused about something...maybe they're experienced and looking for a very specific tip; maybe they've never worked on a car before; or maybe they just forgot a setting or tolerance. Please keep that diversity in mind when writing an article.

The primary way readers find Motorious articles is via search engines like Google, Yahoo, or MSN. Search engines depend on the actual text of a page to understand its content. In light of this, Motorious articles contain the following:

• Relevant keywords in the article to help search engines index the page correctly. For example:
  • List of alternate model names shown in the Procedure Summary (e.g. if a reader Googles for "VW Bug", he should be able to find an article written about "Volkswagen Beetles")
  • Enumerated model years (1968, 1969, 1970, 1971 instead of 1968-1971 means that a search for "1969 VW Bug" will return the correct article)

Articles also contain:

• Clear definiton, scope, and purpose for the procedure
• Description of the procedure itself
• Lots of contextual information (overview, diagrams, photos, etc.)
• Links to related tools, procedures, data, etc.
• In-line links which explain terms, parts, styles, and acronyms (e.g. "barrels", "ports", "plenum", "EGR", etc)

Anatomy of a Motorious article

1. Title

Titles should be clear and simple. Some guidelines:

• Every article is a subpage of a chapter, so including "Chapter title/" before the title will automatically provide a link back to the chapter contents. For example, a correct article name is Engine and clutch/Engine removal not just Engine removal.
• The title should give the topic first and then the action.
  • Use Engine and clutch/Engine removal instead of Engine and clutch/How to remove the engine, Engine and clutch/Removing the engine, Engine and clutch/Steps to remove the engine, etc.
• The title may contain a parenthetical identifier to distinguish it from parallel articles. Some examples:
  • Electrical/Dome light removal (sedan)
  • Electrical/Dome light removal (convertible)
  • Body and frame/Bumper removal (through 1967)
  • Body and frame/Bumper removal (1968 and later)
  • Electrical/Fuse block wiring (6-volt)
  • Electrical/Fuse block wiring (12-volt)
• Note that even if year range is used in the title of the article, the procedure summary (see #4 below) still explicitly lists all applicable model years.
• Write year ranges as inclusive sets ("through 1967" instead of "pre-1968") to ensure that search engines don't incorrectly associate the article with the wrong year (in this example, 1967 is in scope and 1968 is not).

2. Overview

The overview describes the context of the procedure, what the purpose is, etc.

3. System diagram

This diagram or image highlights the relevant part of the larger system for which this procedure applies. It clarifies the context by showing an exploded view or any other meaningful mechanism.

4. Procedure summary

This gives a quick snapshot of the procedure. It lists out all relevant keywords to ensure search engines find the correct article when a user searches using a specific model name and year.

5. Preparation

This section contains useful things to do before this procedure. Use links to other procedures or comments about things to do to make this procedure easier, cleaner, etc.

6. Steps

This is the meat of the article. Each step has a title, description, and photo. In the event that the step is trivial, it's ok to just state the instruction and skip the description and photo.

7. Illustrative photos and diagrams

Use lots of photos and diagrams to indicate exactly what is happening in each step. The photo appears small on the article page, but will be expanded when clicked.

8. Tips, warnings, etc

There are common templates available for highlighting certain comments. For example:

TIP! This is a tip. To insert this into an article, use the following code: {{raw:mot:Tip|Text goes here}}

NOTE! This is a note. Usage: {{raw:mot:Note|Text goes here}}

WARNING: Damage may result! This is a warning about damage. Usage: {{raw:mot:Warning|Text goes here}}

CAUTION: Injury may result! This is a caution about injury. Usage: {{raw:mot:Injury|Text goes here}}

9. Cleanup

This contains information about useful things to do once this procedure is complete. Use links to other procedures or just comments about cleaning up, maintenance, etc.

10. Related links

This is a bulleted list of links to other relevant topics, procedures, tables, data, guides, etc.

11. Article rating

Each Motorious article has a rating (1-5) which indicates its maturity. The details of each of the five ratings are provided here.

Writing style in articles

The style of the actual articles is formal. This is not a newsgroup, forum, or chat room.

• No use of first person or signatures (no "I" or "we", but "you" is ok)
• Don't be cute (i.e. no smileys, humor, sarcasm, etc.)
• No references to people "Bill does it this way..."
• Correct grammar and spelling
• No discourse or dialogue
• No advertising or promotion
• Endorsements and recommendations must be accompanied by data-supported or consensus-based justification

Writing style in discussion pages

Discussion pages are available for every Motorious "content page" or article. To access the discussion page, click the "discussion" tab at the top of the page. Use discussion pages for discussing things if you're unsure about whether or not to put something into the main article. Ask questions there, but put the answers into the main article. You can also use it for polling. For example, in a discussion page about carburetors, you could make a place for people to sign their name if they think progressive carbs are good or bad.

Most of the formal writing restrictions placed on articles are lifted for discussion pages. However, those pages aren't chat rooms either and nonsense will be removed. Be sure to sign your comments in discussion pages:

~~~ signs your name only: Kevinjscott
~~~~ signs your name and inserts the date:  Kevinjscott 12:11, 24 August 2006 (CDT)

About this style guide

If you don't like what you see here, propose a change!