Wiki Style Guide: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
=DevNet Wiki Style Guide= | [[Category:General]]<br />[toc align_right="yes&quot; depth="2&quot;] | ||
= DevNet Wiki Style Guide = | |||
This is a collection of guidelines for writing wiki pages and articles. | This is a collection of guidelines for writing wiki pages and articles. | ||
==Abbreviations== | == Abbreviations == | ||
Abbreviations can be ambiguous. Spell out the term when you use it for the first time followed by the abbreviation in parentheses. | Abbreviations can be ambiguous. Spell out the term when you use it for the first time followed by the abbreviation in parentheses. | ||
'''Example:''' Model View Controller ( | '''Example:''' Model View Controller (MVC) is a software's architecture… | ||
==Headings and Titles== | == Headings and Titles == | ||
===Page and Category Titles=== | === Page and Category Titles === | ||
Use underscores or spaces in your page titles. The wiki engine will convert spaces automatically into underscores in the | Use underscores or spaces in your page titles. The wiki engine will convert spaces automatically into underscores in the URL and underscores into spaces in the title. | ||
Avoid special characters that will break the | Avoid special characters that will break the URL.<br />['''''TODO''': These should be listed; or stated which are allowed (A-Z, a-z, space, underscore, dash(?),'' Volker] | ||
===Headings=== | === Headings === | ||
Keep headings short and use them to structure your article. Avoid links in headings. | Keep headings short and use them to structure your article. Avoid links in headings. | ||
===Capitalization=== | === Capitalization === | ||
Capitalize all nouns and names in the title and headlines of your article. Avoid using all caps. | Capitalize all nouns and names in the title and headlines of your article. Avoid using all caps. | ||
===Table of Contents=== | === Table of Contents === | ||
If your article is longer it is easier for the readers if you provide them a table of contents.<br /> [''''' | If your article is longer it is easier for the readers if you provide them a table of contents.<br />['''''TODO:''' add TOC section to [[TextileSyntax]] and linke here,'' Volker ]<br />['''''TODO''' It's already styted in [[WikiSyntax]].,'' Gerolf] | ||
==Language== | == Language == | ||
Parts of the following apply to all languages, others to English only. Use common sense when adjusting the guidelines to other languages. | Parts of the following apply to all languages, others to English only. Use common sense when adjusting the guidelines to other languages. | ||
===General Writing Style=== | === General Writing Style === | ||
Keep your language understandable and straight to the point and avoid too long and complex sentences. | Keep your language understandable and straight to the point and avoid too long and complex sentences. | ||
| Line 43: | Line 45: | ||
Link to references or related material and check if the links work. | Link to references or related material and check if the links work. | ||
===US-English=== | === US-English === | ||
We prefer US-English, it is commonly used throughout all our sites. | We prefer US-English, it is commonly used throughout all our sites. | ||
===Lists=== | === Lists === | ||
Use the [[TextileSyntax|wiki syntax]] for both ordered and unordered lists. Start every list item with a capitalized word. | Use the [[TextileSyntax|wiki syntax]] for both ordered and unordered lists. Start every list item with a capitalized word. | ||
===References and Links=== | === References and Links === | ||
''coming'' | ''coming'' | ||
==Formatting== | == Formatting == | ||
Use the [[TextileSyntax|formatting options]] the wiki has available. Avoid changing the CSS for single articles since it will interfere with the usability of the site. If you encounter gaps in the current implementation, feel free to report them in the "Beta Forum&quot;:http://developer.qt.nokia.com/forums/viewforum/5/. | |||
'''Exception:''' workarounds needed to support lacking RTL functionality and language specific font-families<br />['''''TODO''' This now works,'' Gerolf] | |||
Revision as of 06:25, 24 February 2015
[toc align_right="yes" depth="2"]
DevNet Wiki Style Guide
This is a collection of guidelines for writing wiki pages and articles.
Abbreviations
Abbreviations can be ambiguous. Spell out the term when you use it for the first time followed by the abbreviation in parentheses.
Example: Model View Controller (MVC) is a software's architecture…
Headings and Titles
Page and Category Titles
Use underscores or spaces in your page titles. The wiki engine will convert spaces automatically into underscores in the URL and underscores into spaces in the title.
Avoid special characters that will break the URL.
[TODO: These should be listed; or stated which are allowed (A-Z, a-z, space, underscore, dash(?), Volker]
Headings
Keep headings short and use them to structure your article. Avoid links in headings.
Capitalization
Capitalize all nouns and names in the title and headlines of your article. Avoid using all caps.
Table of Contents
If your article is longer it is easier for the readers if you provide them a table of contents.
[TODO: add TOC section to TextileSyntax and linke here, Volker ]
[TODO It's already styted in WikiSyntax., Gerolf]
Language
Parts of the following apply to all languages, others to English only. Use common sense when adjusting the guidelines to other languages.
General Writing Style
Keep your language understandable and straight to the point and avoid too long and complex sentences.
It is good practice for online writing to subdivide articles with the help of subheadings. Readers will be able to understand your content more easily if it is presented in a scannable manner.
Add a short introduction to the topic to the beginning of your page. Readers will find out quickly if the article covers what they are looking for.
Link to references or related material and check if the links work.
US-English
We prefer US-English, it is commonly used throughout all our sites.
Lists
Use the wiki syntax for both ordered and unordered lists. Start every list item with a capitalized word.
References and Links
coming
Formatting
Use the formatting options the wiki has available. Avoid changing the CSS for single articles since it will interfere with the usability of the site. If you encounter gaps in the current implementation, feel free to report them in the "Beta Forum":http://developer.qt.nokia.com/forums/viewforum/5/.
Exception: workarounds needed to support lacking RTL functionality and language specific font-families
[TODO This now works, Gerolf]