FIRSTwiki:Style guide
From FIRSTwiki
|
|
Note that this article attempts to explain the most important style considerations. For a more detailed guide, a copy of the Chicago Manual of Style or Strunk and White's The Elements of Style are excellent resources. Also, Wikipedia:Manual of Style, on which this article is based, provides more information.
The policy is currently evolving. See the talk page.
This style guide has the purpose of making things look alike. There are many ways to do things, some equally good -- but if everyone writes according to their own unique style, FIRSTwiki will become less professional, and lose any sense of continuity. Further, a consistent style aids the reader in several ways, making it easier to read articles and providing visual and textual clues to help identify certain features. However, the following quote from the Chicago Manual of Style is worth mentioning:
- Rules and regulations such as these, in the nature of the case, cannot be endowed with the fixity of rock-ribbed law. They are meant for the average case, and must be applied with a certain degree of elasticity.
In other words: rules are meant to be broken, but break them wisely. Borrowing from Wikipedia, bear in mind the following.
Clear, informative and unbiased writing is always more important than presentation and formatting. Writers are not required to follow all or any of these rules: the joy of wiki editing is that perfection is not required. Other FIRSTwikians will refer to this manual when weeding, and pages will be gradually made to conform with this guide.
Please see FIRSTwiki:How does one edit a page for information on how to use all the different forms of markup — there is much more available than just bold or italic. This article concentrates on when to use them, although the examples usually also show the markup.
Contents |
Tone
- First (I, me) and second (you) person should almost never be used. When it seems appropriate to use "you", especially in a how-to, try using "one".
Article Names
The wiki follows Wikipedia's naming conventions. To highlight the most important considerations:
- Spelled-out phrases are preferred to acronyms, unless the subject is almost exclusively known by the acronym. E.g., Continuously variable transmissions as opposed to CVT, but FIRST as opposed to For Inspiration and Recognition of Science and Technology.
- The first letter of the first word should be capitalized, with subsequent letters in lower case. The exception is if the word is a proper noun. E.g., Gracious professionalism, but FIRST Robotics Competition.
- The correct names for FIRST programs are: FIRST Robotics Competition (FRC); FIRST Vext Challenge (FVC); FIRST LEGO League (FLL) and Junior FIRST LEGO League (JFLL)
- If an article is written for a specific year, use the convention "General Title (year)". E.g., Robot Controller talks about what a robot controller is, in general, but Robot Controller (2003) talks about the 2003 version. Note that for team pages, the format is "[team number] in [year]". E.g., 45 in 2003. The exception is to avoid cryptic titles like "45 (2003)".
Links
Free links
Linking is a very important part of the wiki, especially so-called "free links" to other topics such as [[Programming the FRC]]. This is the way that information is organized, and that new content is generated (by linking to pages that don't yet exist). Linking is encouraged, but it should be done reasonably. Link to any article that is relavent and useful to the article being edited. However, don't over do it. Too many links in an article make it confusing to read, and is just plain amateurish. Typically, only the first occurence of a word should be linked to. Note that FIRSTwiki does not make pages specific to certain dates, so these should not be made into links. Also, follow the above naming conventions when creating links to non-existant articles.
It is possible to create links with different names than the article. For instance, [[Downloading a program|download]] displays as download, but links to the article Downloading a program. When linking to non-existant articles, search first to make sure that some other name isn't being used for the same content. Also, never use "click here" as text for a link, since it conveys no information to the reader.
Wikipedia Links
Free links can be made to Wikipedia via Wikipedia template links. The format is very different, {{Wikipedia|name_of_wikipedia_page}}. This is a useful shorthand and is preferred over full URLs. If you want something other than the name of the page as the link text, use {{Wikipedia2|name_of_wikipedia_page|displayed_title}}.
ChiefDelphi Links
Free links can be made to ChiefDelphi via ChiefDelphi template links. The format is very different,{{CD|path_to_chiefdelphi_page}}. This is a useful shorthand and is preferred over full URLs. The path should not contain http://www.chiefdelphi.com/. If you want something other than the name of the page as the link text, use {{CD2|path|displayed_title}}.
ChiefDelphi threads may be directly linked to by using {{CDThread|thread_id}}. To change the displayed text, use {{CDThread2|thread_id|text}}.
External links
FIRSTwiki is not a collection of links and articles with only links is highly discouraged. However, it is often important to link to outside resources -- especially ChiefDelphi, InnovationFIRST, and FIRST. The format for this is single brackets, such as [http://usfirst.org FIRST homepage] that displays as FIRST homepage. Without any text after the URL, the link appears as a footnote. For instance, [http://usfirst.org] displays as [1].
Please note that in most cases, external links should be placed at the end of an article, typically under the heading Resources. This is formed like this:
==Resources==
*[http://
*[http://
Also, if the link is to a non-HTML file, it is good practice to include the file type in parentheses as well as the size for larger files. E.g., IFI Loader v1.0.7 (zip, 4.1 Mb). Note, that when at all possible, it is preferred to link to an HTML page describing a document, rather than the non-HTML document itself. This is out of courtesy, and has other benefits as well.
Headings
To create headings, use the == style markup, not ''' (bold). E.g., ==This is a heading. No blank line is needed after the heading, and, in fact, a blank line should not be used. Headings help readers logically break up an article, and words in headings are given greater weight in searches. Some general guidelines include,
- Capitalize the first word and any proper nouns in headings, but leave the rest lower case.
- Avoid links within headings. Depending on settings, some users may not see them clearly. It is much better to put the appropriate link in the first sentence under the header.
- Overuse of sub-headings should be avoided, as it can make the article look cluttered. Short paragraphs and single sentences generally do not warrant their own sub-heading.
- In circumstances where there is not enough text to justify a sub-heading, it may be preferable to use bolded text or bullet points within a section instead of using sub-headings.
For more information, see Wikipedia:Manual of Style (headings).
Sections
Introduction
All articles should have the title or subject in bold. The title or subject can almost always be made part of the first sentence, but some articles simply have names. E.g.,
- Programming is an integral part of building a robot.
- The default code provides pre-programmed functionality to the robot controller.
If necessary, make the context clear. E.g.,
- In programming, the XOR operation ...
Lead section
The lead section comes before the main article, and when the article has a table of contents, comes before it. It should provide a general introduction to the subject for someone who is unfamiliar with the material. The length depends on the specific article, but in general it should only be a paragraph or two at most.
"See also" section
For short articles that don't have headings, references to articles that have not been linked are handled by See also:.
- ''See also:'' [[Resources for C programming]], [[MPLAB]], [[PIC C]]
will produce,
- See also: Resources for C programming, MPLAB, PIC C
For longer articles with headers, the see also section might be applied to a particular section. Also, it might be given its own header, and alternative formats such as Related topics or Related articles (as headers) are valid.
Page 'Ownership'
The only page any given user 'owns' (if that were applicable in a wiki) is his/her User page and its subpages. Using Goobergunch as an example, he only has exclusive control over the page User:Goobergunch (and its subpages). If there were a page Martin Pyne, he would have no more authority over it than any other user. This also aplies to unregistered contributers, except their 'user' page may be used by someone else who had/will have the same IP address.
