Help:Documentation Guidelines: Difference between revisions From Online Manual

Jump to: navigation, search
(Created page with "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 nei...")
 
mNo edit summary
 
(48 intermediate revisions by 8 users not shown)
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 />Below are the guidelines all Doc Writers and Doc Helpers are asked to follow when working on SMF documentation.<br /><br /><ul class="bbc_list"><li><a href="#post_rules" class="bbc_link">The Rules of Formal/Professional Writing</a></li><li><a href="#post_alternates" class="bbc_link">Alternative Words and Phrasing</a></li><li><a href="#post_standard" class="bbc_link">Standard Terms</a></li><li><a href="#post_style" class="bbc_link">Style Conventions</a></li><li><a href="#post_headings" class="bbc_link">(Sub-)Headings</a></li><li><a href="#post_lists" class="bbc_link">Lists</a></li><li><a href="#post_links" class="bbc_link">Hyperlinking</a></li></ul><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_rules">The Rules of Formal/Professional Writing</span></span><hr />This is a modified list from <a href="http://www.squidoo.com/conversational-vs-formal-writing" class="bbc_link new_win" target="_blank">squidoo.com</a>. We have updated it to fit our needs better.<br /><br /><ul class="bbc_list"><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; Under no circumstances shall you write &quot;it&#039;ll&quot; when you mean &quot;it will!&quot;</li><li><strong>Passive Voice</strong> Nobody threw a ball. Instead, a ball was thrown. No chicken crossed the road; the road was crossed by the chicken.</li><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><li><strong>Never Use &quot;I&quot; or &quot;You&quot;</strong> - Be impersonal.</li><li><strong>Avoid Asking Questions</strong> - People might think you&#039;re trying to be conversational.</li><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><li><strong>Never Use Exclamation Points</strong> - Unless you&#039;re quoting someone, maybe.</li><li><strong>No Sentence Fragments</strong> - That. Would. Be. This. Sort. Of. Thing.</li><li><strong>Refrain From Using Parentheses</strong> - At least, as much as possible.</li><li><strong>Refrain Rrom Using &quot;Etc&quot; or &quot;So On&quot;</strong> - <a href="http://www.english-test.net/forum/ftopic24547.html" class="bbc_link new_win" target="_blank">See here</a> for more information.</li><li><strong>Keep It on Topic</strong> - Link elsewhere for more information.</li><li><strong>Be Clear</strong> - The reader may not know <em>anything</em> about SMF.</li></ul><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_alternates">Alternative Words and Phrasing</span></span><hr />Sometimes, a word just should not be in a document. In the event that this happens, and there are a few exceptions, the list below should help you out.<br /><br /><table class="bbc_table"><tr><td><strong>Word</strong></td><td><strong>Alternative</strong></td><td><strong>Reasoning</strong></td></tr><tr><td>Click</td><td>Select</td><td>We <em>select</em> links and options, but we <em>click</em> the left mouse button.</td></tr><tr><td>Folder</td><td>Directory</td><td>Professionalism.</td></tr><tr><td>You/I/We</td><td>Just don&#039;t use it</td><td>Formalism and Professionalism</td></tr><tr><td>Get (in reference to downloading)</td><td>Download</td><td>Professionalism.</td></tr><tr><td>Tick</td><td>Check</td><td>Professionalism.</td></tr></table><br />The above list is not exhaustive, and Doc Team members may ask you to change words not listed here.<br /><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_standard">Standard Terms</span></span><hr />In an effort to standardize terms across our documentation, please use the following.<br /><br /><ul class="bbc_list"><li><strong>checkbox</strong> - Incorrect though it may be, it&#039;s what SMF uses.</li><li><strong>drop-down list</strong></li><li><strong>login</strong> - This is another example of two words being merged into one. SMF uses it, so the documentation needs to match.</li><li><strong>membergroup</strong> - These show up a lot in SMF, don&#039;t they? <img src="http://www.simplemachines.org/community/Smileys/default/rolleyes.gif" alt="&#58;&#58;&#41;" title="Roll Eyes" class="smiley" /></li><li><strong>smiley</strong></li><li><strong>smileys</strong> - As much as you may want to use &quot;smilies,&quot; don&#039;t. <img src="http://www.simplemachines.org/community/Smileys/default/wink.gif" alt=";&#41;" title="Wink" class="smiley" /></li></ul><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_style">Style Conventions</span></span><hr />Our Online Manual has some things that are specific to it.<br /><ul class="bbc_list"><li><strong>Options</strong> - Options should be in italics. That is to say if you are to select the <em>new topic</em> option, it should be in italics. You can quickly identify options by your urge to put them inside quotes, such as &quot;select the &quot;new topic&quot; option&quot;.</li><li><strong>Directions</strong> - Directions to a particular area or section should be given in the following manner: <em>Admin &gt; Members &gt; Membergroups... &gt; Add Membergroup</em>. Notice the use of italics, spaces, and right angle brackets.</li><li><strong>File Paths</strong> - For directories or files, the path should be separated by forward slashes /.</li></ul><br />The above list is also not exhaustive.<br /><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_headings">(Sub-)Headings</span></span><hr />As demonstrated in this topic, headings may be used within documents to separate logical sections. If a heading is used, it should not be used first. There should always be at least one paragraph of text preceding any headings in a document. To create a heading in a document, simply use <tt class="bbc_tt">&#91;size=4&#93;Title&#91;/size&#93;&#91;hr&#93;</tt> and change &quot;Title&quot; to the title of the heading.<br /><br />If further separation of content is necessary, sub-headings may be used. Sub-headings should always follow headings and never be used outside of them. To create a sub-heading in a document, simply use <tt class="bbc_tt">&#91;b&#93;Title&#91;/b&#93;</tt> and change &quot;Title&quot; to the title of the sub-heading.<br /><br />Never use only one heading or sub-heading. There must always be at least two, otherwise there is no need for them at all. They should also never be bolded, italicized, underlined, colored, linked, or be in all caps or all lowercase letters.<br /><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_lists">Lists</span></span><hr />Lists may be used normally when simply listing options or elements, however there is a specific format for using a list to define or explain items. This format is merely that of bolding the item or term and following it with a hyphen (-) and the definition or explanation. Here&#039;s an example.<br /><br /><ul class="bbc_list"><li><strong>Item 1</strong> - Explanation of Item 1</li><li><strong>Item 2</strong> - Explanation of Item 2</li></ul><br /><span style="font-size: 1.45em;" class="bbc_size"><span id="post_links">Hyperlinking</span></span><hr />Links should always be placed on corresponding words within the normal flow of a proper sentence. Never use &quot;Click here&quot; (or anything similar) or a raw URL when placing a link in a document. Links should never intentionally be bolded, italicized, underlined, colored, or pointed at an off-site location (unless approved by the Doc Team).
{{TOCright}}
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''' - US or British is acceptable.
*'''No sentence fragments''' - All sentences need both a subject and a verb. Exceptions: fragments can be used judiciously in lists.
*'''Avoid slang, jargon, and idioms''' - We have users from all over the world (see "Keep it Simple" above).
*'''Avoid contractions''' - This is in line with a more formal style and it helps non-native readers to understand the text more easily.
*'''No abbreviations''' - Please spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)". Exception: SMF is always an acceptable abbreviation.
*'''Never use exclamation points''' - Unless you are quoting someone.
*'''Avoid parentheses''' - At least, as much as possible. They can make text harder to understand.
*'''Avoid using "etc", e.g. or "so on"''' - Be clear, and use "such as" or "for example" to indicate an incomplete list. "Bright colors such as raspberry and neon green" is easier to understand than "Raspberry, neon green, etc." (interesting discussion at [http://www.english-test.net/forum/ftopic24547.html typical writing style discussion])
*'''Use an instructional style''' in how-to sections, and separate how-to from descriptions.
*'''Link to another page as few times as possible''' - When creating or editing a page try to link to another page as few times as possible, it looks cluttered if the page has multiple links to the same page.
 
===Articles Describing Parts of the Software===
 
These articles describe exactly what can be done on a particular page of the software. It would be confusing to add a how-to that dragged the user across several pages of the software, or through other types of software.  
 
*'''In descriptive sections''' use an impassive, impersonal style. Use active voice where possible, and 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. Remember to keep things simple and clear.
* '''Describe only what can be done on this page''' - If there is a good how-to or FAQ, provide a link.
*'''Refrain from using first person''' (I and we) - Let's not make it about us and them. It's about the page on the screen.
*'''Avoid asking questions''' - User documentation generally should answer questions, not pose them.
 
===FAQs and How-tos===
 
These articles are designed to answer common questions, or explain, step-by-step, a process that might take the user through several pages of their SMF forum. It is still important to be clear, and keep it simple enough for readers from around the world to understand, but it is OK to use slightly less formal language. The reader can be addressed as "you", because the emphasis is on something the reader will accomplish, not just on what options are presented on various pages of the application.
 
==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.
 
{| style="vertical-align: top;" cellspacing="5"
|-
! style="width:20ex; text-align: left" | Avoid using
! style="width:20ex; text-align: left" | Recommended
! style="text-align: left" | Reason
|-
| Folder || Directory
| Consistency. The team's choice -- the term "directory" predates the "folder" metaphor.
|-
| I/We can || The administrator/You may
| Formal style
|-
| Get || Download || Clarity.
|-
| Tick || Check || Consistency.
|-
|Thread || Topic || The SMF software uses "topic", so it is less confusing if we follow that.
|}
<br>
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 and Files===
{{Help:Page names}}
 
===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.
<nowiki>==A Level-Two Heading==</nowiki>
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.
<nowiki>===A Level-Three Heading===</nowiki>
 
All wiki headings should follow the Oxford Manual of Style for capitalisation, which states that the first word and all nouns, pronouns, adjectives, verbs, and adverbs begin with a capital letter, while articles, conjunctions, and short prepositions, generally, do not.
 
===How to Format a List===
{|
|-
|<pre>
* '''Item 1''' - Explanation of Item 1
* '''Item 2''' - Explanation of Item 2
</pre>
|<!-- I really want some padding here. How do I get that? -->&nbsp;&nbsp;&nbsp;&nbsp;
|
* '''Item 1''' - Explanation of Item 1
* '''Item 2''' - Explanation of Item 2
|-
|<pre>
# '''Item 1''' - Explanation of Item 1
# '''Item 2''' - Explanation of Item 2
</pre>
|<!-- I really want some padding here. How do I get that? -->&nbsp;&nbsp;&nbsp;&nbsp;
|
# '''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. Hyperlinks within SMF documentation should only point to URLs at simplemachines.org, with very rare exceptions.
 
{{Help:Linking to terms}}
*'''Proper use of Hyperlink''' - [[Integration hooks]] allow modders to make big changes to SMF without editing the SMF files.
*'''Improper use of Hyperlink''' - Integration hooks allow modders to make big changes to SMF without editing the SMF files. [[Integration hooks|Click here to read more]].
*'''Improper use of Hyperlink''' - Integration hooks allow modders to make big changes to SMF without editing the SMF files (http://wiki.simplemachines.org/smf/Integration_hooks).
 
 
[[Category:Help]]

Latest revision as of 15:44, 15 May 2015

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 - US or British is acceptable.
  • No sentence fragments - All sentences need both a subject and a verb. Exceptions: fragments can be used judiciously in lists.
  • Avoid slang, jargon, and idioms - We have users from all over the world (see "Keep it Simple" above).
  • Avoid contractions - This is in line with a more formal style and it helps non-native readers to understand the text more easily.
  • No abbreviations - Please spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)". Exception: SMF is always an acceptable abbreviation.
  • Never use exclamation points - Unless you are quoting someone.
  • Avoid parentheses - At least, as much as possible. They can make text harder to understand.
  • Avoid using "etc", e.g. or "so on" - Be clear, and use "such as" or "for example" to indicate an incomplete list. "Bright colors such as raspberry and neon green" is easier to understand than "Raspberry, neon green, etc." (interesting discussion at typical writing style discussion)
  • Use an instructional style in how-to sections, and separate how-to from descriptions.
  • Link to another page as few times as possible - When creating or editing a page try to link to another page as few times as possible, it looks cluttered if the page has multiple links to the same page.

Articles Describing Parts of the Software

These articles describe exactly what can be done on a particular page of the software. It would be confusing to add a how-to that dragged the user across several pages of the software, or through other types of software.

  • In descriptive sections use an impassive, impersonal style. Use active voice where possible, and 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. Remember to keep things simple and clear.
  • Describe only what can be done on this page - If there is a good how-to or FAQ, provide a link.
  • Refrain from using first person (I and we) - Let's not make it about us and them. It's about the page on the screen.
  • Avoid asking questions - User documentation generally should answer questions, not pose them.

FAQs and How-tos

These articles are designed to answer common questions, or explain, step-by-step, a process that might take the user through several pages of their SMF forum. It is still important to be clear, and keep it simple enough for readers from around the world to understand, but it is OK to use slightly less formal language. The reader can be addressed as "you", because the emphasis is on something the reader will accomplish, not just on what options are presented on various pages of the application.

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.

Avoid using Recommended Reason
Folder Directory Consistency. The team's choice -- the term "directory" predates the "folder" metaphor.
I/We can The administrator/You may Formal style
Get Download Clarity.
Tick Check Consistency.
Thread Topic The SMF software uses "topic", so it is less confusing if we follow that.


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 and Files

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 the webserver or the wiki to get confused about the article's title.


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

All wiki headings should follow the Oxford Manual of Style for capitalisation, which states that the first word and all nouns, pronouns, adjectives, verbs, and adverbs begin with a capital letter, while articles, conjunctions, and short prepositions, generally, do not.

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: