While there is quite a bit of flexibility when writing your own wiki books, it is important to follow certain best practice rules to ensure that the content provided within the Labdoo platform is of good quality. As a wiki writer, please follow the next recommendations:
-
Keep it simple. You have the option to use HTML markup tags, but it is recommended to only use them if you really need them. An important rule is to keep things simple so they are easier to maintain. When it comes to wiki, simple is better.
-
Use links with relative paths. Please check this wiki entry on how links should be created.
-
Ensure HTML tags are correctly written. Try to not overuse them, but if you do use some HTML tags to format your wiki pages, ensure that they are correctly written. All tags need to have an open clause and a closing clause. For instance:
<em>text here</em>. If your tag does not include any object inside (such as the new line tag <br> or the horizontal line tag <hr>), then you have two options: you can use either <br></br> (without any object between the clauses) or the more compact version <br/>. This first best practice is specially important because the Labdoo system provides automatic back ups of all the wiki content which needs to parse all the wiki pages, and if the tags are not correctly set up, the parsing process can break.
-
If in doubt, follow this wiki book as an example. The wiki book you are reading right now, is made using the same system that you use to write your own. Therefore, if in doubt on how to write a certain page, please come to this guide and check how it was written. As a book writer, you have enough user permissions to click on the "Edit" tab found on the top of each of the pages in this book (make sure you are logged in to see the "Edit" tab), which will allow you to see how each field was filled in.
-
Capitalize titles. Please capitalize the first letter of the words in the title of each wiki page. For instance, the title of this page is "Best Practices", not "best practices" and not "Best practices". This helps keep consistency.
-
Consistency. Please keep consistency across your document. Wiki books can be written in many different ways and styles, but once you decide to do things in a certain way, keep it consistent across your document. This will make your text more pleasant to readers.
-
Spell check and proof read your text. Please ensure that there are no spelling and grammar errors in your text, and make sure you proof read it multiple times. It is very recommended that you have some one else read the text and help you correct it, if possible someone who is good at spelling and grammar. For instance, try to have in your team or community a volunteer that can help you with this task.
-
Save your text often. Make sure you save your text often, this will ensure that your work is properly stored and that your format is correct.