Diaspora Wiki:Wiki style guidelines: Difference between revisions
(Created draft style guide) |
(Headings aren't for styling, they are semantics, so level 3 headings without level 2 headings are invalid) |
||
| Line 1: | Line 1: | ||
== Article titles/headings == | |||
Make titles as concise as possible. Make sure they clearly explain what the page is about. Use a capital letter only for the first word, and for any words which need a capital: for example, "Notes on installing and running Diaspora*". | Make titles as concise as possible. Make sure they clearly explain what the page is about. Use a capital letter only for the first word, and for any words which need a capital: for example, "Notes on installing and running Diaspora*". | ||
== Diaspora* == | |||
Please use the asterisk which is part of Diaspora*'s name. [are we still using this?] | Please use the asterisk which is part of Diaspora*'s name. [are we still using this?] | ||
== Language == | |||
* Use American English, as the most "universal" form of English, but don't use idiomatic English. | * Use American English, as the most "universal" form of English, but don't use idiomatic English. | ||
* Try to make it as universal as possible, so don't use any local idioms (e.g. "awesome!") where they can be avoided. | * Try to make it as universal as possible, so don't use any local idioms (e.g. "awesome!") where they can be avoided. | ||
| Line 11: | Line 11: | ||
* Also keep in mind that many people reading the wiki don't have technical knowledge and are trying to understand how Diaspora* works, so keep technical language/terms/references to a minimum, and explain them where necessary. (The exception to this is of course the technical pages and sections for developers, where technical knowledge can be assumed.) | * Also keep in mind that many people reading the wiki don't have technical knowledge and are trying to understand how Diaspora* works, so keep technical language/terms/references to a minimum, and explain them where necessary. (The exception to this is of course the technical pages and sections for developers, where technical knowledge can be assumed.) | ||
== Structure == | |||
Make sure that your article has a simple and easy to follow structure. If it is a complex subject or a long article, break it up into subsections. Use self-explanatory headings for sub-sections, as these will be listed in a table of contents at the top of the article. If in doubt, ask for some help with editing your article. | Make sure that your article has a simple and easy to follow structure. If it is a complex subject or a long article, break it up into subsections. Use self-explanatory headings for sub-sections, as these will be listed in a table of contents at the top of the article. If in doubt, ask for some help with editing your article. | ||
== Spelling/punctuation == | |||
Use American spelling and punctuation, such as: | Use American spelling and punctuation, such as: | ||
* -ize not -ise | * -ize not -ise | ||
| Line 25: | Line 25: | ||
:: example: U.S.A., not USA | :: example: U.S.A., not USA | ||
== Apostrophes == | |||
Don't use apostrophes when pluralizing abbreviations | Don't use apostrophes when pluralizing abbreviations | ||
:: examples: CDs and DVDs; not CD's or DVD's. | :: examples: CDs and DVDs; not CD's or DVD's. | ||
== Capitalization == | |||
As with headings, only use capital letters where they need to be used, mainly for proper names such as Diaspora*, Ruby on Rails and so on. | As with headings, only use capital letters where they need to be used, mainly for proper names such as Diaspora*, Ruby on Rails and so on. | ||
Revision as of 16:39, 2 July 2013
Article titles/headings
Make titles as concise as possible. Make sure they clearly explain what the page is about. Use a capital letter only for the first word, and for any words which need a capital: for example, "Notes on installing and running Diaspora*".
Diaspora*
Please use the asterisk which is part of Diaspora*'s name. [are we still using this?]
Language
- Use American English, as the most "universal" form of English, but don't use idiomatic English.
- Try to make it as universal as possible, so don't use any local idioms (e.g. "awesome!") where they can be avoided.
- Keep your language as simple as you can – many people reading the wiki will not have English as their first language, so write with them in mind as well as native English speakers.
- Also keep in mind that many people reading the wiki don't have technical knowledge and are trying to understand how Diaspora* works, so keep technical language/terms/references to a minimum, and explain them where necessary. (The exception to this is of course the technical pages and sections for developers, where technical knowledge can be assumed.)
Structure
Make sure that your article has a simple and easy to follow structure. If it is a complex subject or a long article, break it up into subsections. Use self-explanatory headings for sub-sections, as these will be listed in a table of contents at the top of the article. If in doubt, ask for some help with editing your article.
Spelling/punctuation
Use American spelling and punctuation, such as:
- -ize not -ise
- example: "organization" and "decentralized;" not "organisation" or "decentralised."
- double quote marks, with single quote marks for any quotations within a quotation.
- example: He reminded me: "People marked 'Only sharing with me' only see your public posts."
- closing punctuation within quote marks.
- example: "It's not that easy," she said.
- periods/full stops in abbreviations
- example: U.S.A., not USA
Apostrophes
Don't use apostrophes when pluralizing abbreviations
- examples: CDs and DVDs; not CD's or DVD's.
Capitalization
As with headings, only use capital letters where they need to be used, mainly for proper names such as Diaspora*, Ruby on Rails and so on.