[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.

Welcome to the Slackware Documentation Project

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
slackdocs:styleguide [2012/09/04 11:50 (UTC)] – [A General Note on Style] visualize key presses. alienbobslackdocs:styleguide [2012/09/14 21:25 (UTC)] (current) – [Translating a Page] removed text, linked to translation guidelines zithro
Line 95: Line 95:
   * Write complete sentences and try to avoid grammatical errors. If English is not your native language, you can always get help from an English editor.   * Write complete sentences and try to avoid grammatical errors. If English is not your native language, you can always get help from an English editor.
   * Follow proper [[http://www.writersblock.ca/tips/monthtip/tipmar98.htm|capitalization rules]] for words in titles and headings.   * Follow proper [[http://www.writersblock.ca/tips/monthtip/tipmar98.htm|capitalization rules]] for words in titles and headings.
-  * Long passages of plain text are hard to read; always consider if something can be better expressed using a list format. Use numbered lists only for sequential operations, bulleted lists for options or examples (as shown here).+  * Long passages of plain text are hard to read; always consider if something can be better expressed using a list format. Use numbered lists only for sequential operations, bulleted lists for options or examples (as shown here). Sometimes a table or a flowchart can be useful.
   * If quoting computer output, reproduce it exactly, including spelling (which is usually American). Use %%<code></code>%% tags to enclose the output for better legibility.   * If quoting computer output, reproduce it exactly, including spelling (which is usually American). Use %%<code></code>%% tags to enclose the output for better legibility.
   * If your text has examples of key presses, use the %%<key></key>%% markup to make a visual impact. <key>Alt-F2</key> looks better than "''Alt-F2''".   * If your text has examples of key presses, use the %%<key></key>%% markup to make a visual impact. <key>Alt-F2</key> looks better than "''Alt-F2''".
 +  * Avoid the passive voice. Use it only when alternatives would be clumsy.
 +  * Try to avoid long-windedness. "To do x, use the -y option" or "To do x, type [[http://www.techopedia.com/definition/7264/foo|foo]] -y" reads better than "If you want foo to do x for you, you need to type foo -y".
  
  
 ===== Translating a Page ===== ===== Translating a Page =====
  
-The multi-language capability of this Wiki requires that you stick to a few rules+The multi-language capability of this Wiki requires that you stick to a few rules. Please read them in the specific [[slackdocs:translation_guide|Translation Guidelines]].
- +
-  * English is the primary language of the WikiEvery Wiki article must **at least** have an English version. +
- +
-  * When you want to translate a page, you must not change the name of the page. \\ For example to translate [[slackbook:install|slackbook:install]] into Brazilian Portuguese, just add the **pt-br:** prefix in the URL like this: [[pt-br:slackware:install|http://docs.slackware.com/pt-br:slackware:install]] . Do not change the page name "//install//" to its Brazilian Portuguese translation of "//instalar//" ! You should only translate the page's content. +
- +
-  * If you want to create a //new// page in your native language, first create the English version of the page using an English word for the page. A page name like "instalar" is not an English word and therefore will not be accepted. You can start with an empty English page if you want, with just a title for example and containing a large notice that you are working on a translated version first. Then, add your language prefix into the page URL, and start writing your document. +
- +
-<note>A good practice is to put your doc through an automatic translator like [[http://translate.google.com/ | http://translate.google.com/]], paste the translated English text into the empty English page, and post on the [[http://lists.alienbase.nl/mailman/listinfo/slackdocs | slackdocs mailing list]] for help to fix the English translation. //__Creating the English version is a requirement if you want the site editors to accept the article in your own language.__// \\ You should add a note or warning to the English version that it is in need of proof-reading and editing.</note> +
 ===== Pages That Require Attention from an Admin ===== ===== Pages That Require Attention from an Admin =====
  
 slackdocs:styleguide ()