Help:Documentation Guidelines

For the Online Manual we use a very particular approach to writing style, wording, etc. The Online Manual is to be written in a professional and formal way. This paragraph is neither of these. Why? Well, for starters I used "we," which is not the kind of professional or formal writing we want in our documents. Secondly, I used "etc.," which is neither professional nor formal. Thirdly, I asked a question when I said, "Why?"

Below are the guidelines all Doc Writers and Doc Helpers are asked to follow when working on SMF documentation.

The documentation team wants to make the documentation clear and easy for everyone to understand. So it has settled on these guidelines, based on Squidoo's guide to conversational and formal writing, with a few changes to suit this site.

Guidelines for writing SimpleMachines documentation

• Be Clear - The reader may not know anything about SMF.
• Keep It on Topic - Link elsewhere for more information.
• Proper Grammar and Spelling - As taught in US High Schools
• No Sentence Fragments - Usually. All sentences need both a subject and a verb. Exceptions: fragments can be used judiciously in lists
• No Slang or Jargon - It does not "rain cats and dogs." An iPod is not "cool" or "spiffy."
• No Contractions - Write "it is," never "it's." Write "do not," never "don't." Under no circumstances shall you write "it'll" when you mean "it will!"
• No Abbreviations - You will spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)".
• Passive Voice Nobody threw a ball. Instead, a ball was thrown. No chicken crossed the road; the road was crossed by the chicken.
• Never Use Exclamation Points - Unless you're quoting someone, maybe.
• Avoid Asking Questions - People might think you're trying to be conversational.
• Never Use "I", "You", "We", or "Us" - Be impersonal.
• Refrain From Using Parentheses - At least, as much as possible.
• Refrain From Using "Etc" or "So On" - See here for more information.

Word Choice

Words not to use

Some words just work better than others to keep the documentation clear and professional, and to maintain the style the team has selected. Here are some examples of words that generally should not be used.

Word	Alternative	Reason
Click (an option)	Select	Clarity and consistancy. The goal is to select an option. Click is the noise the mouse makes when the left button is depressed.
Folder	Directory	Consistancy. The team's choice -- the term "directory" predates the "folder" metaphor.
You/I/We can	The administrator may	Formal style
Get	Download	Clarity.
Tick	Check	Consistancy.

This list may be updated as the documentation team settles on consitent terms to make the documentation easier to understand.

SMF Words to Use

Some of these words are non-standard. They are to be used in SMF documentation for consistancy with the application interface. These are the terms SMF uses.

• checkbox
• drop-down list
• login - This is
• membergroup one word, rather than two
• smiley - for emoticon
• smileys - This apparant misspelling is used throughout SMF

Elements of Style

Single Word Spelling and Formatting

For consistancy, all SMF documents should use the following conventions:

• Options - "Select the new topic option." The option is in italics when it appears in a sentence.
• Navigational Directions - "Admin > Members > Membergroups... > Add Membergroup". Each navigational element is separated by " > ", and the entire expression is in italics.
• File Paths - For directories or files, the path should be separated by forward slashes /.

The documentation team may add new entries to this list from time to time.

Headings for Sections and Subsections

The title of the document serves as the document's level-one heading. No heading should be used at the top of the document. The document may be divided into sections using level-two headings. If sections are used, there must be two or more. Some introductory material (at least one paragraph) must precede the first section. In this wiki, a level-two heading is created by enclosing the heading text in matching sets of 2 equal signs.

==A Level-Two Heading==

Subsections may be created within sections by using level-three headings. In this wiki, a level-three heading is created by enclosing the heading text in matching sets of 3 equal signs. If subsections are used, there must be two or more subsections in a section. A subsection must always be a part of a section. A level-three heading may never appear before the first level-two heading.

===A Level-Three Heading===

List Formatting

• Item 1 - Explanation of Item 1
• Item 2 - Explanation of Item 2

When a list is used to define or explain terms, options or elements, the term, option, or element (the item) should be bolded, followed by a space, single dash, and space (" - ") and then by the definition or explanation in unbolded text.

Hyperlinking

Hyperlinks should not interrupt the flow of the documentation. Phrases such as "Click here" should not be used to set off the hyperlink, and raw URLs should not be used. Do not add any formatting to hypertext links simply to set them off.

• Proper use of Hyperlink - Documentation writers are encouraged to follow the Help:Documentation_Guidelines documentation guidelines at all times.
• Improper use of Hyperlink" - Documentation writers are encouraged to follow the guidelines. Help:Documentation_Guidelines Click here to read them.
• Improper use of Hyperlink" - Documentation writers are encouraged to follow the documentation guidelines. http://wiki.simplemachines.org/smf/index.php?title=Help:Documentation_Guidelines

Hyperlinks within SMF documentation should only point to URLs at simplemachines.org, with very rare exceptions.