[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
Last revisionBoth sides next revision
slackdocs:styleguide [2012/08/26 21:24 (UTC)] – [Translating a page] sycamorexslackdocs:styleguide [2012/09/08 03:24 (UTC)] – [A General Note on Style] added external definition of "foo" nocturnal.slacker
Line 1: Line 1:
-====== Style guide for articles published at SlackDocs ======+====== Style Guide for Articles Published at SlackDocs ======
  
 A few basic rules should be kept in mind when editing pages in this Wiki. A few basic rules should be kept in mind when editing pages in this Wiki.
  
-===== Page editing etiquette =====+===== Editing Policy =====
  
-==== Release the lock ====+==== Overview ==== 
 + 
 +The Slackware Documentation Project wiki will not be a 100% open wiki. While true that all can contribute, in order to avoid the editing wars and other ill effects experienced by open wikis, staff reviewing of submissions and major page edits will be standard procedure. A contributor will have ownership of his submissions to the extent that he can have a reasonable expectation that the basic structure and content of the article will not be modified without his knowledge and editorial discussion via the discussion page. The Staff feels that this policy would foster a better atmosphere for positive and constructive data archiving on this wiki. 
 +---- 
 + 
 +==== Policy Rule ==== 
 +  
 +**Major ((For purposes of this rule, a major edit should be considered to be any edit that substantially changes the content, flow, or layout of the article.)) edits should not be performed on a contributor's submission without his knowledge and editorial discussion.** 
 + 
 +<note important>A record of the discourse between the contributor and the editor should be present on the discussion page.</note> 
 + 
 +**Exceptions to This Rule** 
 + 
 +  - Core documents in these namespaces that require more exacting editorial overview: **slackware**, **slackdocs** or **slackbook**. 
 +  - Explicit permission is granted via the discussion page by the original author to allow open editing/improvements. 
 +  - Author is unknown or no longer an active participant here. 
 +  - Editing or reversion is required to correct vandalism. 
 +  - Minor edits are required to correct grammar, punctuation, spelling, wiki formatting, or clarity. 
 +  - Editing is required to amend obviously incorrect information.  
 + 
 +<note>For **Exception 6**, a warning note should be placed within the article by a Staff editor stating that the information is incorrect as it currently appears and will be amended soon (once the original contributor has time to respond).</note> 
 +   
 +   
 + 
 + 
 +---- 
 + 
 +==== Commentary ==== 
 + 
 +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. 
 + 
 +===== Page Editing Etiquette ===== 
 + 
 +==== Release the Lock ====
  
 When you click on the "edit" button, you go into "editing mode". In this mode, page or section is **locked** to avoid someone else to edit the page at the same time (creating a conflict). If you close your browser window while you are in "edit" mode, the page lock will not be released for a //maximum of 15 minutes//. Leave the editor using the "cancel" button when you finally decide to not modify the page. This  removes the lock, and permits other people to immediately edit the page. When you click on the "edit" button, you go into "editing mode". In this mode, page or section is **locked** to avoid someone else to edit the page at the same time (creating a conflict). If you close your browser window while you are in "edit" mode, the page lock will not be released for a //maximum of 15 minutes//. Leave the editor using the "cancel" button when you finally decide to not modify the page. This  removes the lock, and permits other people to immediately edit the page.
  
-==== Edit a sectionnot the whole page ====+==== Edit a SectionNot the Whole Page ====
  
 On the right of each page section header, you see the word [edit]. If you click on it to edit the section, you only lock this section of the page which allows other contributors to edit different sections of the page. This is the recommended way for translating pages, fixing typos or just some sentences/words. On the right of each page section header, you see the word [edit]. If you click on it to edit the section, you only lock this section of the page which allows other contributors to edit different sections of the page. This is the recommended way for translating pages, fixing typos or just some sentences/words.
  
-==== Add a summary ====+==== Add a Summary ====
  
 In "edit" mode, you can see an entry field "Edit summary" next to the Save/Preview/Cancel buttons. Use a few words to explain what you have modified. This comment will appear in the "old revisions" tab of the page as well as in the [[http://docs.slackware.com/?do=recent | recent changes]] overview. In "edit" mode, you can see an entry field "Edit summary" next to the Save/Preview/Cancel buttons. Use a few words to explain what you have modified. This comment will appear in the "old revisions" tab of the page as well as in the [[http://docs.slackware.com/?do=recent | recent changes]] overview.
  
-==== Minor modifications ====+==== Minor Modifications ====
  
 When you only fix a typo, change a word, or make global minor modifications, tick the box "Minor Changes" which you find to the right of the "Edit summary" field. Dokuwiki lets us follow page revisions via [[http://docs.slackware.com/feed.php | RSS]]. By indicating that you made a "minor change" you will not trigger an update to the RSS feed. \\ In the "old revisions" tab, minor modifications **will be** mentioned. When you only fix a typo, change a word, or make global minor modifications, tick the box "Minor Changes" which you find to the right of the "Edit summary" field. Dokuwiki lets us follow page revisions via [[http://docs.slackware.com/feed.php | RSS]]. By indicating that you made a "minor change" you will not trigger an update to the RSS feed. \\ In the "old revisions" tab, minor modifications **will be** mentioned.
  
-==== Add a footer ====+==== Add a Footer ====
  
 Every page may end with this wiki code, especially if you copied a text from an external source: Every page may end with this wiki code, especially if you copied a text from an external source:
Line 35: Line 70:
  
  
-===== List of reserved words ===== +===== Note About "Notes" =====
- +
-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> +
- +
- +
-===== Note about "notes" =====+
  
 You can use several visual boxes, like : You can use several visual boxes, like :
Line 65: 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.
  
-===== Translating a page =====+ 
 +=====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. 
 +  * 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. 
 +  * 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). 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 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 =====
  
 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:
Line 71: 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 77: Line 114:
 <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> <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 =====
  
 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 =====
  
 +  * [[slackdocs:staff_editors_guide|Staff Editors Guide]]
 +  * [[slackdocs:contributing|Ideas for Contributing to the SlackDocs Wiki]]
 +  * [[slackdocs:tutorial|Wiki Tutorial and Guidelines]]
 <!-- Please do not add anything below, except additional tags.--> <!-- Please do not add anything below, except additional tags.-->
 <!-- Do not remove this line and the text below. Thanks! slackdocs@ --> <!-- Do not remove this line and the text below. Thanks! slackdocs@ -->
-{{tag>slackdocs syntax}}+{{tag>slackdocs syntax style_guide editing policy}}
 slackdocs:styleguide ()