Difference between revisions of "Instructions to Wiki Editors"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Start writing instructions for wiki editors)
 
m (cleanup/typos)
Line 5: Line 5:


== Spelling and grammar ==
== Spelling and grammar ==
# For consistency sake it is better to use the '''american spelling''' everywhere rather than mix english and american spellings. That means that you should prefer ''color'' and ''finalize'' over ''colour'' and ''finalise''.
# For consistency sake it is better to use the '''American spelling''' everywhere rather than mix English and American spellings. That means that you should prefer ''color'' and ''finalize'' over ''colour'' and ''finalise''.
# Please '''do not use contractions''' (e.g ''If you've navigated'' for ''If you have navigated''). They are usually used in spoken english but not much in written english, although there are some exceptions (e.g. ''It doesn't work'' is fine for non formal written english, as is the expended form ''It does not work''). If in doubt use the expended form. Also the User Manual is a bit more formal than for example an e-mail; and as such contractions that might be fine in an e-mail are not necessarily fine in the User Manual.
# Please '''do not use contractions''' (e.g ''If you've navigated'' for ''If you have navigated''). They are usually used in spoken English but not much in written English, although there are some exceptions (e.g. ''It doesn't work'' is fine for non formal written English, as is the expended form ''It does not work''). If in doubt use the expended form. Also the User Manual is a bit more formal than for example an e-mail; and as such contractions that might be fine in an e-mail are not necessarily fine in the User Manual.
# '''Do not use very complex grammatical structure or abstruse words''' (''abstruse'' meaning ''difficult to comprehend'' and being an example of words to avoid). Keep in mind that many ScummVM users are not native english speaker and many may not speak english as well as you do.
# '''Do not use very complex grammatical structure or abstruse words''' (''abstruse'' meaning ''difficult to comprehend'' and being an example of words to avoid). Keep in mind that many ScummVM users are not native English speakers and may not speak English as well as you do.


== User Manual content ==
== User Manual content ==
# Try to place yourself in the head of a complete newbie and make very explicit some information that might not be obvious for everybody. For example, instead of ''Navigate to the correct directory'' you might want to write ''Navigate to the directory that contains the game files''.
# Try to place yourself in the head of a complete newbie and make very explicit some information that might not be obvious for everybody. For example, instead of ''Navigate to the correct directory'' you might want to write ''Navigate to the directory that contains the game files''.
# ScummVM is distributed on many platforms. When giving instructions on encoding audio or similar tasks try to cover at least Linux, Windows and MacOS X. Most of the users will have one of these operating system.
# ScummVM is distributed on many platforms. When giving instructions on encoding audio or similar tasks try to cover at least Linux, Windows and Mac OS X. Most of the users will have one of these operating system.

Revision as of 15:53, 13 September 2009

These instructions are written mainly with the edition of the User Manual in mind. Some of the points might also be valid for other parts of the wiki though.

No controversial material

The basic rule is to keep in mind that we do not want problems with right holders and therefore we do not want to have links to illegal content or to document steps that might be illegal. An obvious example is links to so-called abandonware sites. Another less obvious example is instructions on how to jailbreak an iPhone or a Wii so that we can install ScummVM. We should write the instructions starting from the assumption that the device is already jail-broken.

Spelling and grammar

  1. For consistency sake it is better to use the American spelling everywhere rather than mix English and American spellings. That means that you should prefer color and finalize over colour and finalise.
  2. Please do not use contractions (e.g If you've navigated for If you have navigated). They are usually used in spoken English but not much in written English, although there are some exceptions (e.g. It doesn't work is fine for non formal written English, as is the expended form It does not work). If in doubt use the expended form. Also the User Manual is a bit more formal than for example an e-mail; and as such contractions that might be fine in an e-mail are not necessarily fine in the User Manual.
  3. Do not use very complex grammatical structure or abstruse words (abstruse meaning difficult to comprehend and being an example of words to avoid). Keep in mind that many ScummVM users are not native English speakers and may not speak English as well as you do.

User Manual content

  1. Try to place yourself in the head of a complete newbie and make very explicit some information that might not be obvious for everybody. For example, instead of Navigate to the correct directory you might want to write Navigate to the directory that contains the game files.
  2. ScummVM is distributed on many platforms. When giving instructions on encoding audio or similar tasks try to cover at least Linux, Windows and Mac OS X. Most of the users will have one of these operating system.