Difference between revisions of "Guidelines: Openideas Wiki"
Latest revision as of 16:45, 19 June 2012
This is a very fast review on how to edit and work with Openideas Wiki, based on Pandora FMS documentation. This could be used for other contents, but at this time, probably is the content with more hours dedicated and the more extent.
1 Main section / Index
All "main" article, book or guide should have a "main index" mage, like for example the Pandora FMS Documentation version at Pandora:Documentation.
This should be used as a "index" with all the capters and links included in it. This also is the page where all pages have the link to "go back/go index".
Content should be "splitted" ind different parts. For example Pandora FMS has 20 chapters and almost 10 annexes. If you want to put all information togheter, will be very difficult to edit and even to read. Try to split chapters using functional concepts.
All chapters should begin with a level-1 section, coded with wiki code like
= This is a level 1 title =
Only should be a level 1 title per chapter, of course, could be exceptions, but in a printed book this will be a physical chapter.
Chapters could have level2, level3 and more depth levels, coded like:
== This is a level 2 title ==
=== This is a level 3 title ===
For limitations in the automatic export metod to ODF, all images should be using the real resolution, this means that except if you want to use the WikiMedia thumb mechanism, you should put all images without resizing. This means that a standard image in our wiki should be uploaded with the final resolution, and coded with a center tag:
<center><br><br> [[image:myfilename]] </center><br><br>
BR tags are not useless, are important to give "space" on the images in the wiki and the ODT export.
3.1 Image sizes
Sometimes is needed to upload a screenshot, and the image size on the original file should be the "real" image size, AND put a special code in the WIKI markup language to resize. Maximum width should be 850px, for example:
<center><br><br> [[image:myfilename|850px]] </center><br><br>
PLEASE, do not use super-small images, there are not useful, but also, don't use giang images.... use the proper size !
4 Export to ODT
Using the Wiki to Print project we're able to export contents of our Wiki to several formats, including OpenOffice ODT (updated recently to Mediawiki v1.5.1).
To generate a three chapter of the contents of Spanish documentation will be a link like:
mw-render --config http://openideas.info/wiki -w odf -o /tmp/pandora_total.odt \ Pandora_3.0:Documentation_es:Introduccion \ Pandora_3.0:Documentation_es:Instalacion \ Pandora_3.0:Documentation_es:Interfaz
Please don't use a frequent use of this feature because it produces a very heavy load in our servers
5 About versions
Sometimes, is needed to describe a new feature. In that case, take in mind following rules / advices :
- Start the chapter / paragraph with "starting with x.x version"....
- Do not use the word "new xxxx", because in the next version that will not be "new" and you need to review all the entries from past versions.
Use it with care, do not flood all the paragraphs with links because it doesn't help, and can confuse. Use just the minimum possible.