AYSO Wiki:Style Guide
Welcome to the AYSO Wiki Style Guide! This page is intended to help us keep a consistent look and feel across the AYSO Wiki to help our readers find the information quickly and get back to the pitch. The primary goal of the wiki is to help our volunteers enact the six philosophies:
Above all, this guide contains guidelines, not rules. Depart from it when doing so improves your content.
Also remember that the wiki is collectively owned by all of us. Do not unnecessarily change the structure of a page, but do not seek permission to improve the site. Work on more than one area, and understand that other people will be working on your area.
Target Audience
AYSO Wiki users are volunteers. They come from a variety of technical and sports backgrounds. They come from every country, language and cultural group. Because of this, the AYSO Wiki strives for a minimum of jargon and direct communication.
Guidelines for All Pages
- use simple English
- prefer bullet points
- include pictures where possible
- link to other pages for details rather than including them directly
- provide captions to images for accessibility
- check that the page looks correct on desktop as well as mobile
Types of Pages
For now, there are two types of pages on the site: Informational and Procedural.
Informational
Informational pages are pages that are intended to help the reader learn something. Because of this, informational pages should be short and easy to skim. If a page takes more than 2-3 pages on a standard laptop, the page should be split into multiple pages.
Readers will skim anything longer than a sentence or two in a paragraph. Avoid information-dense writing and illustrate using bullet points, tables, images, and FAQs.
Avoid humor.
Procedural
For procedural pages, use the imperative mood. This allows the reader to easily understand what actions they are intended to take.
Introductory sentences
In most cases, introduce a procedure with an introductory sentence. This introductory sentence should provide context to the reader that isn't part of the section heading. Don't simply repeat the heading: if the heading explains what the procedure is, and no additional context is needed, then don't include an introductory statement.
The sentence can end with a colon or a period. Use a colon if it immediately precedes the procedure. Use a period if there's more material (such as a note paragraph) between the introduction and the procedure.
You can introduce a procedure with an imperative statement. Don't introduce a procedure with a partial sentence that's completed by the numbered steps.
Single-step procedures
When a procedure consists of only one step, write the step in one sentence and format it as a bulleted list.
Order of multiple components in a step
To document a complex procedural step, use the following order:
- Describe the action to take.
- List a command, if necessary.
- Explain any placeholders that are used in the command.
- Explain the command in more detail, if necessary.
- List the output of the command, if necessary.
- In a separate paragraph, explain the result of an action, or any output, if necessary.
Multiple procedures for the same task
In general, if there's more than one way to complete a task, then document one procedure that's accessible for all readers. If all methods are accessible, pick the shortest and simplest approach if possible. If you need to document multiple ways to complete a task, then separate them in different pages, headings, or tabs.
The following guidelines can help you choose which procedure to document:
- Choose a procedure that lets readers do all the steps by using only a keyboard.
- Choose the shortest procedure.
Steps with goals
For some steps, it's useful to state the goal that the step accomplishes.
When a step includes a goal, state the goal before the action. This structure helps readers understand and complete the step more easily.
Screenshots and videos
Provide screenshots to provide clarity and help the reader verify that they're seeing the correct thing. Videos are also useful to step readers through complicated steps. However, both images and videos can be inaccessible because of visual or motor constraints and web pages may look completely different when viewed from mobile versus laptop versus desktop. Therefore, it is essential that the instructions are clear without the use of images and video.
When uploading a screenshot, the image width can cause the layout of the page to break and side-scrolling if it's too large. Use the custom size to set the width to 800 pixels. MediaWiki will update the number in the height box for you automatically.
Links to documents
Strongly prefer uploading PDFs and other documents directly to the AYSO Wiki rather than linking to outside locations, such as aysovolunteers.org or section websites. The AYSO Volunteers site is transitioning all official content over to the AYSO Wiki, so we should work with content owners to ensure that they are directly updating the PDFs on the Wiki. Other sites (such as section sites) may contain section-specific rules, be out of date, or move without warning. Some groups have been using various section sites as their official hosting locations. Those groups should be strongly encouraged to move their content directly to the AYSO Wiki.
