Differences
This shows you the differences between two versions of the page.
|
wiki_editing_guide [2012/05/13 14:23] ottermaton [Procedures] |
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]]**. |
| - | + | ||
| - | + | ||
| - | ==== Translations ==== | + | |
| - | + | ||
| - | The very basics of doing translations are in the **[[Wiki Translating Basics]]** page | + | |
| - | + | ||
| - | 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. | + | |
| - | + | ||
| - | 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]].** | + | |
| - | + | ||
| - | ==== 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. | + | |
| - | + | ||
| - | If you want to "manually" add an image, the syntax is: | + | |
| - | + | ||
| - | {{:someimage.png}} | + | |
| - | + | ||
| - | 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. | + | |
| - | + | ||
| - | + | ||
| - | ====== 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, 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. | + | |
| ===== Approach to Writing for the Wiki ===== | ===== Approach to Writing for the Wiki ===== | ||
| Line 47: | Line 22: | ||
| 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. | 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. | ||
| + | |||
| + | 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 ===== | ===== Spelling and Grammar ===== | ||
| Use American English spelling and grammar. | Use American English spelling and grammar. | ||
| Line 52: | Line 29: | ||
| Generally speaking, try to avoid using contractions. | Generally speaking, try to avoid using contractions. | ||
| + | ===== 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: | ||
| + | |||
| + | * "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 ===== | ===== Titles ===== | ||
| Line 79: | Line 68: | ||
| 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**. | 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 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. | ||
| + | |||
| + | If you want to "manually" add an image, the syntax is: | ||
| + | |||
| + | {{:someimage.png}} | ||
| + | |||
| + | 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. | ||
| ===== Notes ===== | ===== Notes ===== | ||
| Line 117: | Line 115: | ||
| Note 2.</note> | Note 2.</note> | ||
| - | ===== 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: | ||
| - | * "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. | + | ====== Bodhi Wiki Codes ====== |
| - | * 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. | + | |
| - | * "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 137: | 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 226: | Line 216: | ||
| ---- | ---- | ||
| --- //[[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.1336933419.txt.gz · Last modified: 2012/05/13 14:23 by ottermaton · [Old revisions]