No edit summary |
|||
| Line 5: | Line 5: | ||
This is a modified list from [http://www.squidoo.com/conversational-vs-formal-writing]. We have updated it to fit our needs better.<br /><br /><ul class="bbc_list"><li><strong> | This is a modified list from [http://www.squidoo.com/conversational-vs-formal-writing]. We have updated it to fit our needs better.<br /><br /><ul class="bbc_list"><li><strong> | ||
No Contractions</strong> - 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!"</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 "rain cats and dogs." An iPod is not "cool" or "spiffy."</li><li><strong>Never Use "I" or "You"</strong> - Be impersonal.</li><li><strong>Avoid Asking Questions</strong> - People might think you're trying to be conversational.</li><li><strong>No Abbreviations</strong> - You will spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)".</li><li><strong>Never Use Exclamation Points</strong> - Unless you'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 | No Contractions</strong> - 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!"</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 "rain cats and dogs." An iPod is not "cool" or "spiffy."</li><li><strong>Never Use "I" or "You"</strong> - Be impersonal.</li><li><strong>Avoid Asking Questions</strong> - People might think you're trying to be conversational.</li><li><strong>No Abbreviations</strong> - You will spell out "Internal Revenue Service" at least the first time, providing the abbreviations behind it: "Internal Revenue Service (IRS)".</li><li><strong>Never Use Exclamation Points</strong> - Unless you'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 From Using "Etc" or "So On"</strong> - [http://www.english-test.net/forum/ftopic24547.html| See here] 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'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'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't they? alt="::)" title="Roll Eyes" class="smiley" /></li><li><strong>smiley</strong></li><li><strong>smileys</strong> - As much as you may want to use "smilies," don't. <img src="http://www.simplemachines.org/community/Smileys/default/wink.gif" alt=";)" 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 "select the "new topic" option".</li><li><strong>Directions</strong> - Directions to a particular area or section should be given in the following manner: <em>Admin > Members > Membergroups... > 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">[size=4]Title[/size][hr]</tt> and change "Title" 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">[b]Title[/b]</tt> and change "Title" 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'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 "Click here" (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). | ||
Revision as of 07:24, 18 September 2010
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 Rules of Formal/Professional Writing
This is a modified list from [1]. We have updated it to fit our needs better.
- 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!"
- Passive Voice Nobody threw a ball. Instead, a ball was thrown. No chicken crossed the road; the road was crossed by the chicken.
- No Slang or Jargon - It does not "rain cats and dogs." An iPod is not "cool" or "spiffy."
- Never Use "I" or "You" - Be impersonal.
- Avoid Asking Questions - People might think you're trying to be conversational.
- 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, maybe.
- No Sentence Fragments - That. Would. Be. This. Sort. Of. Thing.
- Refrain From Using Parentheses - At least, as much as possible.
- Refrain From Using "Etc" or "So On" - See here for more information.
- Keep It on Topic - Link elsewhere for more information.
- Be Clear - The reader may not know anything about SMF.
Alternative Words and Phrasing
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.
| Word | Alternative | Reasoning |
| Click | Select | We select links and options, but we click the left mouse button. |
| Folder | Directory | Professionalism. |
| You/I/We | Just don't use it | Formalism and Professionalism |
| Get (in reference to downloading) | Download | Professionalism. |
| Tick | Check | Professionalism. |
The above list is not exhaustive, and Doc Team members may ask you to change words not listed here.
Standard Terms
In an effort to standardize terms across our documentation, please use the following.
- checkbox - Incorrect though it may be, it's what SMF uses.
- drop-down list
- login - This is another example of two words being merged into one. SMF uses it, so the documentation needs to match.
- membergroup - These show up a lot in SMF, don't they? alt="::)" title="Roll Eyes" class="smiley" />
- smiley
- smileys - As much as you may want to use "smilies," don't. <img src="http://www.simplemachines.org/community/Smileys/default/wink.gif" alt=";)" title="Wink" class="smiley" />
Style Conventions
Our Online Manual has some things that are specific to it.
- Options - Options should be in italics. That is to say if you are to select the new topic option, it should be in italics. You can quickly identify options by your urge to put them inside quotes, such as "select the "new topic" option".
- Directions - Directions to a particular area or section should be given in the following manner: Admin > Members > Membergroups... > Add Membergroup. Notice the use of italics, spaces, and right angle brackets.
- File Paths - For directories or files, the path should be separated by forward slashes /.
The above list is also not exhaustive.
(Sub-)Headings
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 [size=4]Title[/size][hr] and change "Title" to the title of the heading.
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 [b]Title[/b] and change "Title" to the title of the sub-heading.
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.
Lists
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's an example.
- Item 1 - Explanation of Item 1
- Item 2 - Explanation of Item 2
Hyperlinking
Links should always be placed on corresponding words within the normal flow of a proper sentence. Never use "Click here" (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).
