Directrices para la Documentación de SliTaz
Este documento provee directrices para la escritura de artículos del wiki y las tareas a realizarse para mantener actualizada la documentación de SliTaz.
Verano de Documentación
-
Complete migration of Handbook and Cookbook (Scratchbook, if possible)
Translation of Handbook and Cookbook
-
Review and update Handbook and Cookbook as of 3.0
Add new guides. A wishlist of guides has been predefined on the
guides page as a starting reference
Review and update existing guides
Instrucciones Generales
Diseño de la Página
There are some definite styles of pages to which we can bring a consistent layout.
FAQ
This applies to one page, Frequently Asked Questions.
Error Message - title the individual
FAQ with the most likely description, usually the error message displayed.
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.
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.
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.
Guías
These resides under the <lang>:guides:<topic> name-space. They describe a process to get something working.
Introduction - Summarize the article
Graphical Way
Manual Way
Installation - Define the packages required and how to install them
Configuration - Explain how to configure files for the proper functioning of packages
Summarize - If possible, summarize all commands in one single script for troubleshooting
Examples and Tips - Add some examples and advanced tips
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
References - Other good reference material on the Internet. If there aren't any, consider a message asking for some!
Manual
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.
Blurb - describes the content of the page, in terms of scope.
Topic - what the user expects to achieve, e.g. 'Image Processing' or 'Desktop Themes'
Body Text - an overview of the topic, with links to relevent Guides or external web pages.
Tips (optional) - any problems the user may experience. Link to
FAQ if answered, forum posts, good problem-solving web pages etc.
Please use correct formatting wherever possible. It aids readability and often lessens ambiguity between commands that should be entered vs. output etc.
Aprender la sintaxis del wiki
aquí. Para probar la sintaxis del wiki, use esta
Playground