Documentation Style Guide

This page presents the house style for the zIFBoards & ZetaBoards Documentation Wiki. Whenever possible, please follow this style guide to ensure a clear and consistent style throughout the wiki.

Organizing Articles

Naming Articles

There are two components to an article’s name: page name and page title. The page name is the component that appears in the page's URL: e.g., this page's name is styleguide. The page title is the name of the article the page contains; this page's title is Documentation Style Guide.

Page names should be short, concise, and always in lowercase. Do not start a page name with an article (e.g., a, an, the). Names should be specific enough that they are unique and give some indication of the page's subject.

Page titles should be in title case—e.g., Documentation Style Guide, not Documentation style guide. When possible, avoid using articles as the first word of a page title. Unlike page names, page titles can be longer if necessary.

Here are some examples of good page names and their corresponding titles:

Name Title
adblock The Hidden Cost of Ad Blocking
newadminfeatures newadminfeatures
report report

Namespaces/Categories

Namespaces, also known as categories, group articles with a common subject together. For example, all the articles about sections of the Admin CP are in the ''acp'' namespace. This style guide is in the wiki namespace. Namespaces can themselves contain sub-namespaces if necessary.

When creating a new page, consider in which category it best belongs. (Consult the wiki index.) Avoid placing the page in the root namespace (i.e., belonging to no category) or in the miscellaneous ''faq'' namespace if there is a better choice. In some cases, you may need find that you need to create a new category. This is fine as long as the category can contain other articles as well; there should never be such a thing as a category with a single article.

The wiki creates new namespaces automatically when you create a page within them. Thus, if you want to create a new page called batman within the new category of superheroes, navigate to superheroes/batman in your browser and click Create new page to get started.

Tags

To associate different articles, even across namespaces, you can add tags to the page using the following syntax:

{{tag>acp moderation autotools multiple_word_tag}}

For consistency, place this syntax at the bottom of pages.

While a page can belong to only a single category, it can have as many tags as applicable. In the future, each tag will link to a page that lists every article so tagged.

Sections

Use headings from Level 1 to 5 to denote hierarchical sections within the article. The first heading, which will also be the article title, should be a Level 1 heading. In most cases, the article title should be the only Level 1 heading on a page, since everything should fall within that scope.

Pages with at least three Level 2 headings will automatically feature a table of contents. The table of contents displays all headings up to Level 3. To suppress the table of contents for some reason, add ~~NOTOC~~ to the page content (preferably at the top).

Avoid using Level 4 or 5 headings when possible. Instead, consider if there is a way to break the content up into more Level 2 or 3 sections.

Article Scope

While the wiki focuses primarily on ZetaBoards documentation, some topics apply to only zIFBoards, and others apply to the entire service. Place the following templates at the top of a documentation to reflect its purpose:

<note zif>This documentation applies to **zIFBoards only**.</note>

This documentation applies to zIFBoards only.

<note zb>This documentation applies to **ZetaBoards only**.</note>

This documentation applies to ZetaBoards only.

Some documentation, such as domain setup, applies to both services:

<note ifzb>This documentation applies to **both** zIFBoards and ZetaBoards.</note>

This documentation applies to both zIFBoards and ZetaBoards.

Article Layout and Tone

Following the article title and its scope, every article should have a brief introductory paragraph. The introduction should define any new terminology used in the article. The precise layout of an article will vary, but two common types of articles are described below.

Avoid writing in a verbose or conversational tone. Keep the introduction and concluding paragraphs short; in the case of tutorials, avoid congratulating the user at the end for completing the tutorial.

Use lists where appropriate to provide concise, structured information. In particular, use ordered lists for steps or instructions. Phrase instructions using the imperative tense. Second person pronouns (“you”) are acceptable in certain declarative sentences; avoid them when giving instructions. For example:

Poor Structure Preferred Structure
You should then click the OK button. Click the OK button.
The foobar should only be used to attack the tarfu. Only use the foobar to attack the tarfu.
If banning occurs, one option is to contact the administrator. If you are banned, one option is to contact the administrator.

Text Formatting

Bold

Use boldface for the following reasons:

  • to indicate parts of a user interface that should be clicked (e.g., buttons and links);
  • to highlight the title of an article or key terms in the introductory paragraph or, less commonly, the key term in the first paragraph of a section;
  • to communicate essential information (e.g., warnings) that should stand out from the rest of the text.

Do not use boldface to emphasize words or phrases; use italics instead.

Italics

Use italics for the following reasons:

  • to draw attention to parts of the user interface (e.g., a heading of a form on an Admin CP page);
  • to emphasize certain parts of a sentence (e.g., “Do not click on that,” or “In this context, forum refers to…”);
  • to highlight a term prior to giving a definition;
  • to refer to the titles of books, plays, movies, and blogs.

Underlining & Strikethrough

Avoid using underlining or strikethrough in documentation. These effects might be useful on special pages; e.g., for keeping track of completed tasks in a list.

Monospacing (Typewriter Text)

Use monospacing, or typewriter text, for the following reasons:

  • to denote a value that should be entered into a field (e.g., “Click the Date field and enter d-m-Y g:I.”);
  • to denote placeholders (e.g., “When you visit http://yourdomain.com/, you should receive a message that it is pointing to the server…”);
  • to refer to code, such as BBCode tags, HTML elements or JavaScript functions, inline (e.g., “Use the [flash] tag to include a video.”).

Use internal links to link to other pages on the wiki. (The link button on the formatting toolbar has a navigation tool to help build a link if you are unsure of the syntax.) Here are some examples of internal links:

Input Output
[[wiki/syntax|Formatting Syntax]]
Formatting Syntax
[[wiki:syntax|Formatting Syntax]]
Formatting Syntax
[[wiki/syntax#lists|Tips on formatting lists]]
Tips on formatting lists

Link to other pages that contain related or additional information that the reader might find helpful. Avoid linking to the same page more than once. Linking to pages that haven't been created yet is encouraged; when doing so, refer to the conventions on naming articles above.

An external link looks like the following:

Input Output
[[http://www.zetaboards.com/|ZetaBoards website]]
ZetaBoards website

Do not use external links to link to other parts of the wiki.

Images

Screenshots are an essential feature of documentation. Refer to the syntax for images for help resizing and aligning images.

  • Upload all images to the wiki. Do not use externally hosted images.
    • Upload an image to the same namespace as the page that will be using it, unless the image will likely be used on more than one page.
    • Give the image a descriptive name. If it is part of a sequence of screenshots, number each image according to its place in the sequence.
  • Crop a screenshot to show only the relevant part of a page.
  • Consider limiting the width of an image if its exceptionally wide (or tall). The wiki links to the original image unless explicitly told otherwise.
  • Highlight a section of an image using a 1 px to 3 px red box outline. Avoid using additional features, such as arrows, circles, or lines, to draw attention to a section. To highlight multiple sections, use a different colour of box.

Notes

Highlight important points using the following types of notes.

<note styletype>Note goes here!</note>

Warning notes provide information that may prevent an error or unexpected behavior of the forum. They should be used in situations involving dataloss, such as deletion of members.

Under Construction pages may need information that is not yet available, or may be in the ScreenshotQueue. Either way, tag it so that people know the information contained there is not yet complete.

Important notes provide information that should not be overlooked, as it is crucial to proper function of the forum.

Tip notes provide handy shortcuts that can help make managing a forum easier. Feel free to create tips for advanced users, as well as ones for everyone.

Normal notes provide any information that is not markedly important or handy. You can use them to provide background information or a related feature. You do not need to include a styletype.

Community Involvement pages are specially-marked so that everyone can make changes to them. Although they take more care (since destructive edits must be reversed), they can often be useful to collect info.



wiki/styleguide.txt · Last modified: 2015/01/09 16:02 (external edit)