User:Jcreer/Style Guide

This style guide is to be used in creating and editing articles for GMS, SMS, and WMS.

Article Guide

For consistency, articles should follow a similar format and style.

Article Titles

All articles must have a unique title. The title should indicate the subject of the article with clarity and simplicity. Long titles should be avoided. Articles should start with the appropriate prefix for each product—GMS: for GMS, SMS: for SMS, and WMS: for WMS. If the subject of the article clearly applies to all programs, do not include a prefix.

Capitalize each word in the title.

Redirects

Redirects are helpful in directing users to the correct article for a subject. Most articles should have redirect pages that link to it. For example, an article about a Preferences dialog could be entitled either "Preferences" or "Preferences Dialog." Whichever title the article is given, the other title should be used as a redirect page.

Do not create double-redirects. A double-redirect is a redirect that goes to another redirect page.

Redirects are coded as following:

#redirect $[[$article title$]]$

Article Length and Content

Articles should be long enough to give the reader enough information that multiple questions can be answered without needing to go to another article. Short articles should be avoided as they cause users to have to conduct a longer search to find what they need.

Long articles contain more information that what the user will need. A long article is acceptable if it is easy to navigate, such as making good use of headings and having a clear table of contents.

Stub Articles

In general, short articles should be marked as stub article and placed in the stub category. A stub article is a short article that could user further development. In general if an article has fewer than 250 words of content, than is is likely that the article does not contain enough information to be useful. An exception to this rule might be if the article has a large detailed graphic or multiple useful graphics.

Merging Articles

Short articles that cannot be expanded should be looked at to see if they can be merged with another article.

When merging articles, select one article and place all information in that article. For the other article, replace the content with a redirect to the article where the content is now located. Change all links and redirects from the merged article so that they go to the new article. Do not create double-redirects.

Article Components

Each article has multiple components.

Intro

All articles should begin with a short paragraph that directly explains what the article is about. Neatly summarize what will be discussed in other sections of the article when appropriate. Do not begin an article with a subtitle or other heading.

Sections

Organize articles into sections to help make the article more readable. Use wiki headings to delineate sections. When using headings, start with level two heading and work down in order. Do not skip levels.

Article Table of Contents

The wiki will automatically generate a table of contents for an article that has more than three headings. It is not advisable to hide the table of contents. The table of contents may appear in an unusual place in the article depending on where the first heading starts. The placement of the table of contents can be moved. Large table of contents that have more than seven items can be moved to the right side of the page using the TOCright template.

Infoboxes

Most articles do not require an infobox. Infoboxes can be used for two purposes.

1. To give a summary of a large topic.
2. To provide navigation links on a large subject.

Related Topics

When appropriate, end articles with a section entitled "Related Topics." This section should contain links to pages with closely related content. Avoid placing an excessive number of links in this section, one or two links should be enough. Avoid having more than four links in this sections. It is not necessary to include every article related to the topic. For example, an article on using nodestrings in the mesh module could have a link to the main mesh module page. A link to every article about nodestrings or the mesh module would be inappropriate.

Long list of links to help navigate a complex topic, such as the mesh module, should place in an infobox or navbox.

Navbox and Categories

Every page should be included in a category. Categories make it easier to see all pages related to a certain topic which both makes the pages easier to find and easier to update if there is a major change.

Every product have a navbox that should be included at the bottom of each article.

Graphics and Images

When possible, it is best to include graphics in articles.

What to Include

Include graphics that will enhance the article topic. Examples of dialogs, windows, and screenshots will help users gain a better understanding of the subject of the article. Whenever possible include a picture of dialog in the article that discusses how to use that dialog.

Uploading Images

A couple rules should be followed when uploading images.

1. Make certain the image file has a unique name.
2. Select an image name that will give some indication of what the image is about.
3. Only give a file the same name as a file already existing in the wiki if intending to replace the existing image.
4. Place the caption for the image on the file page as well as the article page. This helps users know where the image belongs if it gets removed from its article page.
5. Place the image in the correct category. This helps keeps images organized.

Positioning

Images can be positioned anywhere on the page. However, good judgement should be used in placement. Remember that when placing images in a wiki, different users may see the images displays in different locations on the page depending on the browser being used and the screen size. Make certain that the image placement has some flexibility.

Do not place a large picture in the middle of a paragraph of text. Place large graphics to the left or to the right, or before or after the paragraph.

Captions

Include a caption on most images. Images can get separated from the related text, so having a caption helps the reader match the text and image. Include the caption on both the image placed on the article page and on the file page for the image.

Small images that can be included in the text line, such as icons, do not need a caption in the article page, but a caption should still be included on the image file page.

Tables and Charts

When to Use a Table

Tables can be convenient ways to organize information. They can also be confusing if not organized correctly. To determine if a table is necessary, look at the information that would be presented. Does the information require repeating the same information over and over again? How many rows and columns would the final table have? How large would the final table be?

Keep in mind that the table needs to be printable from the wiki.

Table Formatting

In general, using the standard "wikitable" format is acceptable.

In many cases, the standard wikitable formatting does not make it sufficiently clear that the presented items are in table format. In this case, add a 1 pixel width border.

Some tables should have no formatting. These tables should be used when positioning items in a table where there the user shouldn't be able to tell that the items have been laid out using a table.

Formatting Code

Code should be formatted using a space in front of each line of code to enable the wiki standard code formatting text. An example of this format is show below.

Code format example.
   Example
Code example

This format changes the font of the text and will maintain spaces in the code.

If using the space method doesn't work or makes the code confusing, then it is often best to place the code in an un-formatted table.

Writing Guide

For consistency, follow the writing tips and format in this section when creating an article.

Writing Tips

To write better articles follow these tips:

• Write clearly. Use correct grammar and standard spelling.
• Do not write less than required. If the information is not on the page, do not assume the reader will understand what is meant intuitively.
• Do not write more than required. It's not necessary to repeat ideas multiple times.
• In general, write in the third-person point of view. Avoid using "I," "we," or "you."
• Avoid using the passive voice.
• Include all of the steps when explain how to follow a process. Do not assume that a step is intuitive or that the reader will have read a previous article.
• Remember that a reader can come to an article from anywhere. Have enough in an article to make reading the article worth the reader's time.
• Do not create articles that are mostly links to other articles. These are often a waste of the user's time and can leave a reader feeling like we are giving them the runaround.

Writing Format

The following format guide should be applied to most articles.

Emphasis

When wanting to place emphasis on a word, such as a dialog name, use the following guidelines:

• Bold: use bold to emphasize commands, buttons, tools, and elements that will either bring up a new dialog or window, or will immediately activate a process. This includes the following in most situations: menu commands, buttons, tools, etc…
• Italics: use italics for elements that are stationary text, such as the names of dialogs, field names, menus, submenus, tabs, etc… If it is uncertain whether something should be bold, italic, or in quote marks, use italics.
• “Quote marks”: Use quote marks for places where the user will be typing in text or may be typing text. This should be names of items that the user may change as well as number data entered into the fields manually. Quote marks should be use to when referring to a specific file by name. In summary, use quote marks around : file names, files in the project explorer, items in dropdown menus, data fields.
• Underlining: just don’t.
• Strikethrough: also not to be used often. It can be used for information that is obsolete, but this will not be clear to most users. It is better to clearly indicate that information is obsolete with a heading or some other written method.