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 revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
slackdocs:styleguide [2012/09/03 21:27 (UTC)]
nocturnal.slacker [A General note on Style]
slackdocs:styleguide [2012/09/08 03:24 (UTC)]
nocturnal.slacker [A General Note on Style] added external definition of "foo"
Line 34: Line 34:
 ==== Commentary ==== ==== Commentary ====
  
-Regarding the Core namespaces **slackware**,​ **slacdocs**, and **slackbook**;​ these are the heart of this project. While howtos and other sections of the wiki are also important to the project, the Core documentation is the reason for all our efforts here. With this in mind, the Staff believes that content in these sections should be more minutely edited and maintained. The more exacting oversight utilized in the care of these Core documents will be appreciated by those using this project as a resource in their learning and continuing use of Slackware Linux.+Regarding the Core namespaces **slackware**,​ **slackdocs**, and **slackbook**;​ these are the heart of this project. While howtos and other sections of the wiki are also important to the project, the Core documentation is the reason for all our efforts here. With this in mind, the Staff believes that content in these sections should be more minutely edited and maintained. The more exacting oversight utilized in the care of these Core documents will be appreciated by those using this project as a resource in their learning and continuing use of Slackware Linux.
  
 Thank you for your understanding and cooperation in this matter. Thank you for your understanding and cooperation in this matter.
Line 67: Line 67:
  
 {{tag>​list of tags}} {{tag>​list of tags}}
-</​code>​ 
- 
- 
-===== List of Reserved Words ===== 
- 
-There is a list of reserved words used by Dokuwiki as shortcut word. 
- 
-<​note>​need to explain the use</​note>​ 
- 
-<​code>​ 
-FIXME 
-= footer = (with one or many level ===) 
 </​code>​ </​code>​
  
Line 100: Line 88:
 The button bar at the top of the edit window contains buttons for easy creation of these notification boxes. The button bar at the top of the edit window contains buttons for easy creation of these notification boxes.
  
-=====A General note on Style==== 
  
-This is a wiki so a certain degree of informality is acceptable. This includes, for example, conversational contractions such as "​you'​ve"​. Readers should feel that they are talking to a knowledgeable friend rather than reading a manual. However any appearance of sloppiness must be avoided. +=====A General Note on Style==== 
-  * Do not use slang or "​textspeak"​.+ 
 +This is a wiki so a certain degree of informality is acceptable. This includes, for example, conversational contractions such as "​you'​ve"​. Readers should feel that they are talking to a knowledgeable friend rather than reading a manual. Howeverany appearance of sloppiness must be avoided. 
 +  * Do not use [[wp>​Slang|slang]] or "[[wp>​SMS_language|textspeak]]".
   * 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.
-  * Capitalize ​proper ​names and the main (subject-oriented) ​words in 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).+  * 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''"​. 
 +  * 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 =====
  
Line 114: Line 108:
   * English is the primary language of the Wiki. Every Wiki article must **at least** have an English version.   * English is the primary language of the Wiki. Every 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 ​http://​docs.slackware.com/​slackware:​install into Brazilian Portuguese, just add the **pt-br:** prefix in the URL like this: 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.+  * When you want to translate a page, you must not change the name of the page. \\ For example to translate ​[[slackware:install|slackware:​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.   * 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.
Line 124: Line 118:
 If you think that a Wiki page (written by somebody else or by yourself) is in need of attention from the admin team, you can add a tag "​needs_attention"​ to that page. This will cause the affected page to show up on the "​[[tag:​needs_attention|pages that need attention]]"​ page. The admin team will check that page regularly for new entries. If you think that a Wiki page (written by somebody else or by yourself) is in need of attention from the admin team, you can add a tag "​needs_attention"​ to that page. This will cause the affected page to show up on the "​[[tag:​needs_attention|pages that need attention]]"​ page. The admin team will check that page regularly for new entries.
  
-When should you use this? For instance, you find an incomplete or badly written text or even an empty page (this can happen if someone writes a non-english ​text but does not take action to get a proper ​english ​translation arranged). Or perhaps you find spam, or offensive language. \\ Your observations will help us keep the Wiki clean and high-quality.+When should you use this? For instance, you find an incomplete or badly written text or even an empty page (this can happen if someone writes a non-English ​text but does not take action to get a proper ​English ​translation arranged). Or perhaps you find spam, or offensive language. \\ Your observations will help us keep the Wiki clean and high-quality.
  
 ===== See Also ===== ===== See Also =====

In Other Languages
QR Code
QR Code slackdocs:styleguide (generated for current page)