Help:Documentation Guidelines: Difference between revisions From Online Manual

Jump to: navigation, search
(html + warning regarding question marks in titles)
Line 1: Line 1:
<!--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 &quot;we,&quot; which is not the kind of professional or formal writing we want in our documents. Secondly, I used &quot;etc.,&quot; which is neither professional nor formal. Thirdly, I asked a question when I said, &quot;Why?&quot;<br /><br />
<!--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?"<br /><br />
--><!-- An example of "what we don't want to see", right at the top?-->
--><!-- An example of "what we don't want to see", right at the top?-->
The documentation team wants to make the documentation clear and easy for everyone to understand. So it has settled on these guidelines. Everyone who works on SMF documentation at this site is encouraged to follow these guidelines.
The documentation team wants to make the documentation clear and easy for everyone to understand. So it has settled on these guidelines. Everyone who works on SMF documentation at this site is encouraged to follow these guidelines.


== General Guidelines ==
== General Guidelines ==
<ul class="bbc_list">
* Do '''not''' use question marks (?) in any page title.
<li><strong>Be Clear</strong> - The reader may not know <em>anything</em> about SMF.</li>
*'''Be Clear''' - The reader may not know ''anything'' about SMF.
<li><strong>Keep It on Topic</strong> - Link elsewhere for more information.</li>
*'''Keep It on Topic''' - Link elsewhere for more information.
<li><strong>Keep It Simple</strong> -- Not everyone reads English easily</li>
*'''Keep It Simple''' -- Not everyone reads English easily.
<li><strong>Proper Grammar and Spelling</strong> - As taught in US High Schools</li>
*'''Proper Grammar and Spelling''' - As taught in US High Schools.
<li><strong>No Sentence Fragments</strong> - Usually. All sentences need both a subject and a verb. Exceptions: fragments can be used judiciously in lists</li>
*'''No Sentence Fragments''' - Usually. All sentences need both a subject and a verb. Exceptions: fragments can be used judiciously in lists.
<li><strong>No Slang or Jargon</strong> - It does not &quot;rain cats and dogs.&quot; An iPod is not &quot;cool&quot; or &quot;spiffy.&quot;</li>
*'''No Slang or Jargon''' - It does not "rain cats and dogs." An iPod is not "cool" or "spiffy".
<li><strong>No Contractions</strong> - Write &quot;it is,&quot; never &quot;it&#039;s.&quot; Write &quot;do not,&quot; never &quot;don&#039;t.&quot;</li>
*'''No Contractions''' - Write "it is," never "it's." Write "do not," never "don't".
<li><strong>No Abbreviations</strong> - You will spell out &quot;Internal Revenue Service&quot; at least the first time, providing the abbreviations behind it: &quot;Internal Revenue Service (IRS)&quot;.</li>
*'''No Abbreviations''' - You will spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)".
<li><strong>Never Use Exclamation Points</strong> - Unless you&#039;re quoting someone.</li>
*'''Never Use Exclamation Points''' - Unless you're quoting someone.
<li><strong>Avoid Asking Questions</strong> - User documentation generally should answer questions, not pose them.</li>
*'''Avoid Asking Questions''' - User documentation generally should answer questions, not pose them.
<li><strong>Refrain From Using Parentheses</strong> - At least, as much as possible.</li>
*'''Refrain From Using Parentheses''' - At least, as much as possible.
<li><strong>Refrain From Using &quot;Etc&quot; or &quot;So On&quot;</strong> - Other constructions (such as those that appear in a [http://www.english-test.net/forum/ftopic24547.html typical writing style discussion]) are more clear or more formal.</li>
*'''Refrain From Using "Etc" or "So On"''' - Other constructions (such as those that appear in a [http://www.english-test.net/forum/ftopic24547.html typical writing style discussion]) are more clear or more formal.
<li><strong>Refrain from using First and Second person</strong> I, we, you -- let's not make it about us and them</li>
*'''Refrain from using First and Second person''' I, we, you -- let's not make it about us and them.
<li><strong>In descriptive sections</strong> use an impassive, impersonal style. Use active voice where possible, passive voice where necessary to put the emphasis correctly.  Sometimes, to put the emphasis on the road, it is necessary to say "the road was crossed by the chicken".  But not usually.</li>
*'''In descriptive sections''' use an impassive, impersonal style. Use active voice where possible, passive voice where necessary to put the emphasis correctly.  Sometimes, to put the emphasis on the road, it is necessary to say "the road was crossed by the chicken".  But not usually.
<li><strong>Use an Instructional Style</strong> in how-to sections, and separate how-to from descriptions</li>
*'''Use an Instructional Style''' in how-to sections, and separate how-to from descriptions.
</ul><br />
 


==Word Choice==
==Word Choice==
Line 36: Line 36:
<tr><td>You/I/We can</td><td>The administrator may</td><td>Formal style</td></tr>
<tr><td>You/I/We can</td><td>The administrator may</td><td>Formal style</td></tr>
<tr><td>Get</td><td>Download</td><td>Clarity.</td></tr>
<tr><td>Get</td><td>Download</td><td>Clarity.</td></tr>
<tr><td>Tick</td><td>Check</td><td>Consistancy.</td></tr></table>
<tr><td>Tick</td><td>Check</td><td>Consistency.</td></tr></table>
<br />
<br />
This list may be updated as the documentation team settles on consitent terms to make the documentation easier to understand.
This list may be updated as the documentation team settles on consistent terms to make the documentation easier to understand.


===SMF Words to Use===
===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.
Some of these words are non-standard. They are to be used in SMF documentation for consistency with the application interface. These are the terms SMF uses.
<ul class="bbc_list">
*'''checkbox'''
<li><strong>checkbox</strong></li>
*'''drop-down list'''
<li><strong>drop-down list</strong></li>
*'''login'''
<li><strong>login</strong></li>
*'''membergroup''' one word, rather than two
<li><strong>membergroup</strong> one word, rather than two</li>
*'''smiley''' - for emoticon
<li><strong>smiley</strong> - for emoticon</li>
*'''smileys''' - This apparent misspelling is used throughout SMF
<li><strong>smileys</strong> - This apparant misspelling is used throughout SMF</li></ul>
 


==Other Elements of Style==
==Other Elements of Style==
===Single Word Spelling and Formatting===
===Single Word Spelling and Formatting===
For consistancy, all SMF documents should use the following conventions:
For consistency, all SMF documents should use the following conventions:
<ul class="bbc_list">
 
<li><strong>Options</strong> - "Select the ''new topic''  option."  The option is ''in italics'' when it appears in a sentence.</li>
*'''Options''' - "Select the ''new topic''  option."  The option is ''in italics'' when it appears in a sentence.
<li><strong>Navigational Directions</strong> - "''Admin &gt; Members &gt; Membergroups... &gt; Add Membergroup''".  Each navigational element is separated by " &gt; ", and the entire expression is in italics.</li>
*'''Navigational Directions''' - "''Admin > Members > Membergroups... > Add Membergroup''".  Each navigational element is separated by " > ", and the entire expression is in italics.
<li><strong>File Paths</strong> - For directories or files, the path should be separated by forward slashes /.</li></ul><br />
*'''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.
The documentation team may add new entries to this list from time to time.


Line 95: Line 95:


===Hyperlinking===
===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.Hyperlinks within SMF documentation should only point to URLs at simplemachines.org, with very rare exceptions.
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. Hyperlinks within SMF documentation should only point to URLs at simplemachines.org, with very rare exceptions.


{{Help:Linking to terms}}
{{Help:Linking to terms}}

Revision as of 13:12, 7 March 2012

The documentation team wants to make the documentation clear and easy for everyone to understand. So it has settled on these guidelines. Everyone who works on SMF documentation at this site is encouraged to follow these guidelines.

General Guidelines

  • Do not use question marks (?) in any page title.
  • Be Clear - The reader may not know anything about SMF.
  • Keep It on Topic - Link elsewhere for more information.
  • Keep It Simple -- Not everyone reads English easily.
  • 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".
  • No Abbreviations - You will spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)".
  • Never Use Exclamation Points - Unless you're quoting someone.
  • Avoid Asking Questions - User documentation generally should answer questions, not pose them.
  • Refrain From Using Parentheses - At least, as much as possible.
  • Refrain From Using "Etc" or "So On" - Other constructions (such as those that appear in a typical writing style discussion) are more clear or more formal.
  • Refrain from using First and Second person I, we, you -- let's not make it about us and them.
  • In descriptive sections use an impassive, impersonal style. Use active voice where possible, passive voice where necessary to put the emphasis correctly. Sometimes, to put the emphasis on the road, it is necessary to say "the road was crossed by the chicken". But not usually.
  • Use an Instructional Style in how-to sections, and separate how-to from descriptions.


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.

WordAlternativeReason
Click (an option)SelectClarity and consistancy. The goal is to select an option. Click is the noise the mouse makes when the left button is depressed.
FolderDirectoryConsistancy. The team's choice -- the term "directory" predates the "folder" metaphor.
You/I/We canThe administrator mayFormal style
GetDownloadClarity.
TickCheckConsistency.


This list may be updated as the documentation team settles on consistent 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 consistency with the application interface. These are the terms SMF uses.

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


Other Elements of Style

Single Word Spelling and Formatting

For consistency, 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.

Naming articles, categories, files on the wiki

Follow the wiki naming convention used at Wikipedia.

  • Use lower case only (there are very few exceptions)
  • Avoid abbreviations in article titles
  • Avoid all punctuation in article titles. The characters "?" and "&" are not permitted in article titles, because they can cause difficulty interpreting the article's URL.

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===

How to format a list

* '''Item 1''' - Explanation of Item 1
* '''Item 2''' - Explanation of Item 2
    
  • Item 1 - Explanation of Item 1
  • Item 2 - Explanation of Item 2
# '''Item 1''' - Explanation of Item 1
# '''Item 2''' - Explanation of Item 2
    
  1. Item 1 - Explanation of Item 1
  2. 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. Hyperlinks within SMF documentation should only point to URLs at simplemachines.org, with very rare exceptions.

When we create pages, there are often times terms that we would like to define with definitions on other wiki pages. For instance forum or member. Please use them wisely. Remember your audience. If you're directing documentation at developer's of customizations, it only serves to complicate the documentation by having links back to "forum" on the page. So, here goes a simple rule:

Link back to terms that relate to the level of user you're documenting for.



Advertisement: