Differences
This shows you the differences between two versions of the page.
|
wiki_editing_guide [2012/05/03 16:24] mardhi [Buttons and Windows] |
wiki_editing_guide [2012/07/28 09:00] (current) mardhi [Approach to Writing for the Wiki] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Wiki Editing Guide ====== | + | ====== Bodhi Linux Wiki Editing and Style Guide ====== |
| + | ===== Introduction ===== | ||
| - | All users are permitted and encouraged to participate in the adding to and the editing of the Bodhi Wiki. Only a few key pages are restricted from editing by normal users. We use DokuWiki software to run this wiki. Refer to the **[[http://www.dokuwiki.org/dokuwiki|DokuWiki site]]** for information on its usage, particularly the **[[http://www.dokuwiki.org/syntax|Dokuwiki Syntax Page]]** | + | All users are permitted and encouraged to participate in contributing to and editing the Bodhi Wiki. Only a few key pages are restricted from editing by normal users. We use DokuWiki software to run this wiki. Refer to the **[[http://www.dokuwiki.org/dokuwiki|DokuWiki site]]** for information on its usage, particularly the **[[http://www.dokuwiki.org/syntax|Dokuwiki Syntax Page]]**. |
| - | You can create and test pages in the **[[playground:playground|Playground]]** | + | To ensure consistency throughout the wiki, follow this style guide when creating or editing wiki pages. Feel free to add to the style guide whenever you think of a word or style choice that should be used consistently across the wiki pages. |
| - | ==== Creating Pages ==== | + | |
| + | You can create and test pages in the **[[playground:playground|Playground]]**. | ||
| + | |||
| + | |||
| + | ===== Creating Pages ===== | ||
| When creating a wiki article, give some thought to the pagename you are creating for that article. The "primary" or "most significant" word in the title should be the first word. In nearly all cases this will also be a noun. | When creating a wiki article, give some thought to the pagename you are creating for that article. The "primary" or "most significant" word in the title should be the first word. In nearly all cases this will also be a noun. | ||
| Line 11: | Line 16: | ||
| Note that the //pagename// and //title// do not have to be the same. See **[[pagenames and namespaces]]** for further explanation. | Note that the //pagename// and //title// do not have to be the same. See **[[pagenames and namespaces]]** for further explanation. | ||
| - | If you would like to see what pages have been created / edited recently, just **[[http://wiki.bodhilinux.com/doku.php?do=recent | go here]]** | + | If you would like to see what pages have been created / edited recently, just **[[http://wiki.bodhilinux.com/doku.php?do=recent | go here]]**. |
| + | ===== Approach to Writing for the Wiki ===== | ||
| + | When writing, assume users have minimal knowledge of how to use Bodhi Linux; add enough detail for a novice to understand you and, where possible, use non-technical language. | ||
| - | ==== Translations ==== | + | Avoid jokes and convoluted, conversational language; jokes aren't universally funny, and even less so if a user wants to quickly find the information that they need! Do not interpret this as meaning that your writing will be cold or unfriendly; in the context of a wiki, the user will appreciate neutral and concise language more than "personality" that you want to display. |
| - | The very basics of doing translations are in the **[[Wiki Translating Basics]]** page | + | Apart from spelling and grammar, which is to be in the American English style, when choosing between styles to use, give preference to the style that is already most used in existing wiki pages so that as few pages as possible need to be updated. This rule can be broken if there is a good reason why a new style or word should be used over the dominant style or word. If a style decision can't be reached through this method, then use common sense. |
| + | ===== Spelling and Grammar ===== | ||
| + | Use American English spelling and grammar. | ||
| - | If you are doing translations, please make sure you have a thorough understanding of **[[pagenames and namespaces]]**. The short version is: for the translation plugin to work correctly all the pages in each language must have the same **pagename**. It is the **namespace** (think of them as a folder/directory) that keeps them distinct. | + | Generally speaking, try to avoid using contractions. |
| - | When you are creating a link to a page in most cases you will want to take advantage of the feature that allows you to create a link that displays substitute text. It takes the form of | + | ===== Preferred Words and Styles ===== |
| - | [[actual link | visible text]] | + | This is an alphabetized list of preferred words and styles that aren't covered by the rule of using American English as a preference: |
| - | Here's an example of it in use from the German **[[de:using bodhi | Using Bodhi]]** page: | + | |
| - | [[user - add new | Benutzer hinzufuegen]] | + | |
| - | The link goes to the page "user - add new" but displays the link as "Benutzer hinzufuegen" | + | |
| - | If you have questions just ask on the **[[http://www.bodhilinux.com/forums/index.php?/forum/22-documentation/|Documentation sub-forum]].** | + | * "Bodhi Linux" the first time it's referred to on a page, "Bodhi" thereafter unless it appears after another top level heading on the same page. |
| + | * "display" rather than "screen" when referring to anything to do with the operating system environment; screen should only refer to the physical screen of the computer. | ||
| + | * double quotation marks (") rather than single quotation marks (') | ||
| + | * En dash (–) rather than em dash (—) | ||
| + | * "forward slash" (rather than "solidus") | ||
| + | * forward slashes have no space on either side of them, unless needed for a code to work. | ||
| + | * "Internet" always capitalized | ||
| + | * "press" (rather than "touch" when referring to performing actions with a touchscreen. | ||
| + | * "touchscreen" (rather than "touch screen", "touch-screen", or "TouchScreen") | ||
| + | |||
| + | ===== Titles ===== | ||
| + | With a few exceptions, all words in a title of an article or the title of a section should be capitalized. | ||
| + | |||
| + | The only types of words in titles that should __not__ be capitalized are articles, prepositions, conjugations and the particle "to" when it is used with an infinitive __unless__ they are the first or last word of a title. | ||
| + | |||
| + | ===== Capitalization ===== | ||
| + | Apart from in titles, only capitalize proper nouns. There is no need to capitalize a generic reference to an element of the Bodhi operating system, but you should capitalize an element of the operating system if it is the proper name of the element. For example, you shouldn't capitalize a reference to a terminal, but you should capitalize a reference to Bodhi's default terminal, LXTerminal. | ||
| + | |||
| + | ===== Procedures ===== | ||
| + | Number each step of a procedure and place each step on a new line. | ||
| + | |||
| + | Only include one instruction per step unless the step is simple or related enough to the next step to make it appropriate to join the steps. | ||
| + | |||
| + | For a closely-related string of steps, it is appropriate to use the -> arrow (inserted by writing a hyphen and then a closing angle bracket, e.g., - > without a space) to link steps with only one initial verb. For example, "Click **Terminal** -> **Set Character Encoding** -> **Add or Remove...**". Put a space on either side of the arrows and don't bold them. | ||
| + | |||
| + | If the result of a correctly executed step has a visible result, such as a window opening, include the result on the line below the step, but don't number it. | ||
| + | |||
| + | |||
| + | |||
| + | |||
| + | |||
| + | |||
| + | ===== Buttons and Windows ===== | ||
| + | Try to reserve the bold character style for buttons and windows. For example, "Click **Ok**." Otherwise, it may be confusing whether bolded text is referring to a button or window, or whether it's being used for another reason, like to add emphasis. | ||
| + | |||
| + | When writing about multiple buttons to be pressed simultaneously, use an addition symbol seperated by a space between the buttons, and bold the buttons and the addition symbol: **Alt + Esc**. | ||
| - | ==== Images ==== | + | ===== Images ===== |
| Images can be uploaded via the //Add Images and other files// button on the top bar of the **Edit Window** on any page. Browse through your system to find the file you want to upload and select it. Once it is uploaded, you can then just click on the file you just uploaded and it will appear in your text where you last had the cursor. | Images can be uploaded via the //Add Images and other files// button on the top bar of the **Edit Window** on any page. Browse through your system to find the file you want to upload and select it. Once it is uploaded, you can then just click on the file you just uploaded and it will appear in your text where you last had the cursor. | ||
| Line 37: | Line 78: | ||
| Technically, the leading colon is not required in the default **namespace**, but it is __required__ in other **namespaces**. Since it may cause confusion when a page is translated but the image does not appear it is highly recommended to use the leading colon. | Technically, the leading colon is not required in the default **namespace**, but it is __required__ in other **namespaces**. Since it may cause confusion when a page is translated but the image does not appear it is highly recommended to use the leading colon. | ||
| - | ==== Adding Notes to a Page ==== | + | ===== Notes ===== |
| - | If you want to make a piece of text really stand out, use the Note plugin by enclosing the text in the suitable note tags: | + | If you want to draw attention to a piece of particularly important or useful text, use the Note plugin by enclosing the text in the suitable note tags: |
| <note tip></note> | <note tip></note> | ||
| Line 73: | Line 114: | ||
| Note 2.</note> | Note 2.</note> | ||
| - | ====== Bodhi Wiki Style Guide ====== | ||
| - | To ensure consistency throughout the wiki, follow this style guide when creating or editing wiki pages. Feel free to add to the style guide whenever you think of a word or style choice that should be used consistently across the wiki pages. | ||
| - | |||
| - | When choosing between styles to use, preference should be given to the style that is already most used in existing wiki pages so that as few pages as possible need to be updated. This rule can be broken if there is a good reason why a new style or word should be used over the dominant style or word. | ||
| - | |||
| - | ===== Titles ===== | ||
| - | Unless they are the first or last word of a title, the only types of words in titles that should not be capitalized are articles, prepositions, conjugations and the particle "to" when it is used with an infinitive. | ||
| - | |||
| - | ===== Spelling and Grammar ===== | ||
| - | Use American English spelling and grammar. | ||
| - | |||
| - | ==== Capitalization ==== | ||
| - | Apart from in titles, only capitalize proper nouns. There is no need to capitalize a generic reference to an element of the Bodhi operating system, but you should capitalize an element of the operating system if it is the proper name of the element. For example, you shouldn't capitalize a reference to a terminal, but you should capitalize a reference to Bodhi's default terminal, LXTerminal. | ||
| - | |||
| - | ==== Buttons and Windows ==== | ||
| - | Try to reserve the bold character style for buttons and windows. For example, "Click **Ok**." Otherwise, it may be confusing whether bolded text is referring to a button or window, or whether it's being used for another reason, like to add emphasis. | ||
| - | |||
| - | When writing about multiple buttons to be pressed simultaneously, use an addition symbol seperated by a space between the buttons, and bold the buttons and the addition symbol: **Alt + Esc**. | ||
| - | ===== List of Preferred Words and Styles ===== | ||
| - | This is an alphabetized list of preferred words and styles that aren't covered by the rule of using American English as a preference: | ||
| - | * double quotation marks (") rather than single quotation marks (') | + | ====== Bodhi Wiki Codes ====== |
| - | * En dash (–) rather than em dash (—) | + | |
| - | * "forward slash" (rather than "solidus") | + | |
| - | * forward slashes have no space on either side of them, unless needed for a code to work. | + | |
| - | * "press" (rather than "touch" when referring to performing actions with a touchscreen. | + | |
| - | * "touchscreen" (rather than "touch screen", "touch-screen", or "TouchScreen") | + | |
| - | + | ||
| - | ====== Using Bodhi Wiki Codes to Create Elements of a Wiki Page ====== | + | |
| ===== Links ===== | ===== Links ===== | ||
| Line 111: | Line 125: | ||
| ==== Link Style ==== | ==== Link Style ==== | ||
| - | When creating a link contained in a section of text please enclose it in 2 asterisks to make the link bold. Like so: | + | When creating a link contained in a section of text, enclose it in 2 asterisks to make the link bold. For example: |
| Go to **[[Start]]** | Go to **[[Start]]** | ||
| Will look like this: Go to **[[Start]]** | Will look like this: Go to **[[Start]]** | ||
| Links that appear in a list of links do not need to be highlighted by bolding. A good example of both is the **[[Getting Started]]** page. | Links that appear in a list of links do not need to be highlighted by bolding. A good example of both is the **[[Getting Started]]** page. | ||
| + | |||
| + | Apply usual grammar rules to sentences with links, including placing a period after a link. But don't make the period part of the link unless the period is usually part of the link anyway. | ||
| ===== Section Headings ===== | ===== Section Headings ===== | ||
| Line 131: | Line 147: | ||
| - | ===== Fonts ===== | + | ===== Font Styles ===== |
| ==== Filenames and Code ==== | ==== Filenames and Code ==== | ||
| When referring to a filename or a short command that is inside a block of text, please surround it with 2 single quotes. It will look like this: ''filename.txt'' | When referring to a filename or a short command that is inside a block of text, please surround it with 2 single quotes. It will look like this: ''filename.txt'' | ||
| ''filename.txt'' | ''filename.txt'' | ||
| - | When including a long command and/or path, start a newline and indent 2 or more spaces to create a "quote box" (This is how the boxes for the above syntax examples have been created). Alternatively (sometimes the first character in the text you are quoting will misinterpreted by Dokuwiki), surroud it with the tags | + | When including a long command and/or path, start a newline and indent 2 or more spaces to create a "quote box" (This is how the boxes for the above syntax examples have been created). Alternatively (sometimes the first character in the text you are quoting will be misinterpreted by Dokuwiki), surround it with the tags |
| <code> </code> | <code> </code> | ||
| - | ==== Keywords (Applications/Topics) ==== | + | ==== "Objects" (Keywords/Applications/Topics/Buttons/etc) ==== |
| - | References to another application or that are a keyword for another topic should be styled in **bold text**. | + | References to another application or those that are to a keyword for another topic should be styled in **bold text**. Menu Selections or Buttons that are pressed in an application should also be in **bold text**. |
| - | <code>**Make text bold with asterisks**</code> | + | <code>Make text **bold** with asterisks</code> |
| - | ==== Buttons/Menu Options ==== | + | ==== Actions ==== |
| - | When referring to Menu Selections or buttons that are pressed in an application use //italic text//. | + | References to actions that you are instructing a user to do should be in //italics//. Some examples would be: click, navigate, type, etc |
| - | <code>//Use slashes to make italics//</code> | + | <code>Make text //italicized// with forward slashes</code> |
| ===== Comments in a Page ===== | ===== Comments in a Page ===== | ||
| - | There is a plugin installed in **Bodhi Wiki** that allows you to leave comments in the source for yourself or other authors. | + | You may leave comments in the page source for yourself or other authors which is not visible when viewing a page normally. |
| This is the syntax: | This is the syntax: | ||
| Line 171: | Line 188: | ||
| than one line on */ multiple lines. | than one line on */ multiple lines. | ||
| ===== User Feedback Poll ===== | ===== User Feedback Poll ===== | ||
| - | There's a plugin added that can display a user feedback poll. For instructional/how-to type articles we would like to know if the article is useful for our users. Please add this bit of code **WITH ONE IMPORTANT EDIT** (see below) to the bottom of these type of pages: | + | Please add a **User Feedback Poll** to each page that is of an instructional or how-to nature so that we can collect feedback on how useful an article is to our users. Add this bit of code __WITH ONE IMPORTANT EDIT__ (see below) to the bottom of these type of pages: |
| <code> | <code> | ||
| ---- | ---- | ||
| Line 185: | Line 202: | ||
| </code> | </code> | ||
| - | The edit to make is to the 3rd line: | + | You will edit the 3rd line: |
| <code> | <code> | ||
| <vote vote_test3 check=ip> | <vote vote_test3 check=ip> | ||
| </code> | </code> | ||
| - | Change the "''vote_test3''" to the pagename of the article **withOUT spaces**. For example, this page would be: | + | Change the "''vote_test3''" to the pagename of the article, substituting any spaces with underscores(_). For example, this page would be: |
| <code> | <code> | ||
| <vote wiki_editing_guide check=ip> | <vote wiki_editing_guide check=ip> | ||
| Line 196: | Line 213: | ||
| That text is the "name" of the poll. If it isn't changed all votes will go to the same poll, not what we want. | That text is the "name" of the poll. If it isn't changed all votes will go to the same poll, not what we want. | ||
| - | FYI: the "''check=ip''" part is there to allow only one vote per ip to prevent skewing of results. | + | <note tip>The "''check=ip''" part is there to allow only one vote per ip to prevent skewing of results.</note> |
| ---- | ---- | ||
| --- //[[mark@linuxisit.com|mark]] 2011/06/11 13:39// | --- //[[mark@linuxisit.com|mark]] 2011/06/11 13:39// | ||
| + | |||
| + | ===== Translations ===== | ||
| + | |||
| + | The very basics of doing translations are in the **[[Wiki Translating Basics]]** page. | ||
| + | |||
| + | If you are translating, ensure that you have a thorough understanding of **[[pagenames and namespaces]]**. The short version is that for the translation plugin to work correctly all the pages in each language must have the same **pagename**. It is the **namespace** (think of them as a folder/directory) that keeps them distinct. | ||
| + | |||
| + | When you are creating a link to a page in most cases you will want to take advantage of the feature that allows you to create a link that displays substitute text. It takes the form of | ||
| + | [[actual link | visible text]] | ||
| + | Here's an example of it in use from the German **[[de:using bodhi | Using Bodhi]]** page: | ||
| + | [[user - add new | Benutzer hinzufuegen]] | ||
| + | The link goes to the page "user - add new" but displays the link as "Benutzer hinzufuegen". | ||
| + | |||
| + | If you have questions just ask on the **[[http://www.bodhilinux.com/forums/index.php?/forum/22-documentation/|Documentation sub-forum]].** | ||
wiki_editing_guide.1336076643.txt.gz · Last modified: 2012/05/03 16:24 by mardhi · [Old revisions]