SliTaz Repositories

     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/pages/guidelines.txt	Sat Feb 26 12:10:20 2011 +0000
     1.3 @@ -0,0 +1,98 @@
     1.4 +====== SliTaz Documentation Guidelines =====
     1.5 +This document provides guidelines on writing a wiki article and the tasks to be performed to make SliTaz documentation up-to-date.
     1.6 +
     1.7 +//
     1.8 +//
     1.9 +
    1.10 +===== Summer of Documentation =====
    1.11 +    - Centralization of all documentation to http://doc.slitaz.org 
    1.12 +    - Complete migration of Handbook and Cookbook (Scratchbook, if possible) 
    1.13 +    - Translation of Handbook and Cookbook
    1.14 +    - Link or translate the wiki articles on the [[http://labs.slitaz.org|labs website]]
    1.15 +  - Review and update Handbook and Cookbook as of 3.0
    1.16 +  - Add new guides. A wishlist of guides has been predefined on the [[http://doc.slitaz.org/en:guides:start| guides page]] as a starting reference 
    1.17 +  - Review and update existing guides
    1.18 +
    1.19 +//
    1.20 +//
    1.21 +
    1.22 +===== General Instructions =====
    1.23 +  * **Add** : Feel free to add any pages to the wiki  
    1.24 +    * __Namespaces or Documentation Hierarchy__ : Documentation Hierarchy structure has been defined for the English language. Please follow it as a standard while creating pages.  Some examples :
    1.25 +      * //en:handbook:start// : Handbook start page
    1.26 +      * //en:handbook:desktop// : Desktop is a page link on the handbook start page. All handbook pages should have the namespace "en:handbook:" 
    1.27 +      * //en:guides:faq// : All guides pages should have namespaces "en:guides". To create a faq page, simply do <nowiki> [[faq | FAQ]] </nowiki>. This will automatically create a faq page with the en:guides:faq namespace
    1.28 +      * //Index// : Links can be used to see the hierarchy structure
    1.29 +    * __Add Images__ : Use the toolbar and add images to the relevant namespaces
    1.30 +  * **Delete** : Simply remove all the contents of the pages to delete a page
    1.31 +  * **Review** :  Each page should contain a review section. For example, [[http://doc.slitaz.org/guidelines#formatting|see the bottom of this page]]. A review section is just a wiki table. You are free to edit the table and/or add extra rows to the table. You can translate it into your own language. You can also copy and paste the page review table on this page to any of the wiki pages and edit accordingly
    1.32 +
    1.33 +//
    1.34 +//
    1.35 +
    1.36 +===== Page Layout  =====
    1.37 +
    1.38 +There are some definite styles of pages to which we can bring a consistent layout. 
    1.39 +
    1.40 +=== FAQ ===
    1.41 +
    1.42 +This applies to one page, [[en:guides:faq|Frequently Asked Questions]].
    1.43 +
    1.44 +  - **Error Message** - title the individual FAQ with the most likely description, usually the error message displayed.
    1.45 +  - **Symptoms** - a brief description of what the user may experience when this FAQ applies. There may be more than one. Use correct formatting when describing on-screen messages, keystrokes etc. Hopefully, Google results will pick this up.
    1.46 +  - **Explanation** - a not-very-technical explanation of the error message. Users will be able to understand the problem and how it can be resolved in a high-level sense.
    1.47 +  - **Solution** - how to solve the problem, technically. Include brief descriptions of the steps needed rather than merely a list of commands; this is important to understand what the user needs to do. Individual problems have slightly different solutions -- use levels of bullet points etc. to organise it.
    1.48 +
    1.49 +
    1.50 +=== Guides ===
    1.51 +
    1.52 +These resides under the <lang>:guides:<topic> name-space. They describe a process to get something working.
    1.53 +
    1.54 +  - **Introduction** - Summarize the article  
    1.55 +  - **Graphical Way** 
    1.56 +     * Instructions - How to use the graphical tool (if it exists) 
    1.57 +     * Screenshots - A picture is worth a thousand words
    1.58 +  - **Manual Way**
    1.59 +     * Installation - Define the packages required and how to install them 
    1.60 +     * Configuration - Explain how to configure files for the proper functioning of packages 
    1.61 +     * Summarize - If possible, summarize all commands in one single script for troubleshooting
    1.62 +  - **Examples and Tips** - Add some examples and advanced tips
    1.63 +  - **FAQ/Troubleshooting** - Some DIY instructions or a sub-section on problems/symptoms/solutions/notes or a link to forum posts. Link to FAQ if answered there
    1.64 +  - **References** - Other good reference material on the Internet. If there aren't any, consider a message asking for some!
    1.65 +
    1.66 +
    1.67 +=== Handbook ===
    1.68 +
    1.69 +These reside under the <lang>:handbook:<topic> namespace. They brief the reader on what SliTaz can offer on a particular topic. They are an overview and description and not a guide, though they may contain (very) few steps on how to get up-and-running.
    1.70 +
    1.71 +  - **Blurb** - describes the content of the page, in terms of scope.
    1.72 +  - **Topic** - what the user expects to achieve, e.g. 'Image Processing' or 'Desktop Themes'
    1.73 +  - **Body Text** - an overview of the topic, with links to relevent Guides or external web pages.
    1.74 +  - **Tips** (optional) - any problems the user may experience. Link to FAQ if answered, forum posts, good problem-solving web pages etc.
    1.75 +
    1.76 +
    1.77 +
    1.78 +//
    1.79 +//
    1.80 +
    1.81 +===== Formatting =====
    1.82 +
    1.83 +Please use correct formatting wherever possible. It aids readability and often lessens ambiguity between commands that should be entered vs. output etc.
    1.84 +
    1.85 +  * Learn wiki syntax [[http://doc.slitaz.org/wiki:syntax?s[]=playground | here]]. For testing wiki syntax, just use the [[http://doc.slitaz.org/en:guides:playground| Playground]] page
    1.86 +
    1.87 +\\
    1.88 +---- 
    1.89 +\\
    1.90 +^  Page Review Section  ^^ 
    1.91 +|Quality| Good  |
    1.92 +|Review| Needs to be reviewed |
    1.93 +|Priority| Medium |
    1.94 +|Problems| add a [[http://forum.slitaz.org|forum post link]]|
    1.95 +|:::     | OR add a [[http://labs.slitaz.org/issues |lab issue tracker link ]]|
    1.96 +|How to Improve| Suggest briefly, e.g.,|
    1.97 +|::: |  [[http://labs.slitaz.org/wiki/packages | New package testing guidelines are here]]  |
    1.98 +|::: | Add new rows like this ;-)  |
    1.99 +
   1.100 +\\
   1.101 +----
   1.102 \ No newline at end of file

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/pages/start.txt	Sat Feb 26 12:10:20 2011 +0000
     2.3 @@ -0,0 +1,40 @@
     2.4 +~~NOTRANS~~
     2.5 +
     2.6 +====== SliTaz documentation ======
     2.7 +
     2.8 +\\
     2.9 +\\
    2.10 +Please select your language:
    2.11 +
    2.12 +**[[cn:start|Chinese]] - [[de:start|Deutsch]] - [[en:start|English]] - [[es:start|Español]] - [[fr:start|Français]] - [[id:start|Indonesian]] - [[pt:start|Português]] - [[ru:start|Русский]]**
    2.13 +\\
    2.14 +\\
    2.15 +\\
    2.16 +===== About this Site =====
    2.17 +\\
    2.18 +This site is the central place for all SliTaz documentation. The Wiki site supports full translations. The main language is English and please try and keep the documentation hierarchy.
    2.19 +
    2.20 +
    2.21 +==== Spread SliTaz Wiki ====
    2.22 +Share this page or another one on your Blog, Twitter, Identica account or Like this page on Facebook to help us spread Slitaz all around the world and make it even more famous and popular! You can also "Like" the official [[http://www.facebook.com/slitaz|SliTaz Facebook page]] 
    2.23 +
    2.24 +{{like>url=http://doc.slitaz.org/}}
    2.25 +
    2.26 +==== Contributing ====
    2.27 +
    2.28 +If you'd like to help with the documentation, jump in! Take a look at the [[guidelines| SliTaz Documentation Guidelines]], pick your page and go!
    2.29 +
    2.30 +There's many areas in which you can help:
    2.31 +
    2.32 +  * **Are you an experienced SliTaz user?**
    2.33 + Go for the Guides. They take users through a process and range from customising your desktop to getting networking set-up.
    2.34 +  * **Are you a general Linux user?**
    2.35 +Take a look at the Handbook. A lot of general introduction to SliTaz, Linux or available software can be written there. Some people find it difficult to write technically, others struggle with more generically informative writing. Both are needed, in describing the topic and scope before brief instructions.
    2.36 +  * **Are you a non-English speaker?**
    2.37 +Translations are very important to the global audience SliTaz attracts. We need speakers of the above languages to ensure non-English readers experience better translations than automated services can provide! Those are the locales supported by the SliTaz system. We are aiming to add more in the future -- if you can help, please do!
    2.38 +
    2.39 +//There are more ways to help out with the SliTaz community than documentation. If you're interested, everything from artwork to package testing would be greatly appreciated! Simply post a quick message to the forum or mailing list, or see the [[en:guides:contributor|Contribution]] page for how you can get started. Thanks!//
    2.40 +
    2.41 +==== Exporting to static book ====
    2.42 +Dokuwiki can export wiki content to xHTML so we will be able to provide a static version of SliTaz books for offline reading. See the xHTML export of this page http://doc.slitaz.org/start?do=export_xhtmlbody. We may also install a plugin to enable PDF export.
    2.43 +