Projects in the open source world usually always in need of documentation. Bad documentation or non existent documentation is something that they have struggle to eradicate. Developers sometimes put their compilers away and dedicate some time to write about all the classes and functions that have been written during the past few months. But this doesn’t always happen let alone be up to date.
So users, new contributors, people that want to understand the code, and want to get instant contributions, documentation might be a good area to start with. Why? Because on one side you will learn a lot about what is documented, not just the content but the style and organization. On the other side, you will actually learn about what has been documented including past functions, examples, and snippets.
Wikis are a great way to produce documentation, but if you never touched one aside from the random Wikipedia search. You should understand some key aspects of it:
- wiki language – markup of the wiki, formatting, labels, tables, images, and more
- history – each page has a history of edits, make sure to read the comments
- history differential – review changes as the documentation came to become
- editors – check out the common editors of the wiki, they can be great mentors, usually their nicks are in the history
- watch pages – provide a subscription to the changes of a page, check your settings if you want alerts by email
- styles – understanding structure, wiki books, standard labels
- comments – use comments withing the wiki to ask/add clarification
- translations – localization of the documentation is even more needed, some wikis are internationalized, make sure you learn the process to localize wiki pages, verify they are up to date.
- code highlighting – improving formatting on snippets is to add the highlight to the code to improve readability.
All these are expanded on the documentation of the wiki the project is using, usually open source projects prefer open source wikis, the most used are:
- mediawiki
- moin moin
- dokuwiki
- confluence wiki
- trac
- github/google code/sourceforge wiki
Each has their own markup differences, but in general you should understand how your formatting can become better by looking at heavy formatted pages withing the wiki. Tables, layouts, images, text blocks, menus, etc. All these elements combine to make a very boring wiki into a very appealing web-site like and easy to read and follow. Headers are a good way to break content withing the page.
Besides the technical aspect is important to communicate the work you do on the wiki to the rest of the community. New documentation is always well received and even users can comment and contribute fixing possible spelling mistakes. There are some old ways that you will need to rethink about content as you work with wikis.
Wikis are about collaboration, various people working on a single body of work. For that reason you need to be more bold and fix others people writeup without waiting on their permission. The same is expected from you, from other people modifying your work. Remember this is not YOUR work, but the work of the community. So your work is meant to be modified.
Spelling, grammar, and technical mistakes are easy to change, however more structural changes might need some leading role. For example, if a new version of a software is launched, should you rewrite the whole site detailing the new information, or should you create a new page with the new information of the new version. These topics need to be discussed on the mailing list, but at the same time, remember that changing a page is easier than deleting one. So working withing the created pages provide less future problems (since you can go back in time), than creating new ones (which only administrators can delete permanently). This is also something to keep in mind when you create new pages.
More complex wikis use extensions which improve the editing and readability of a wiki. Wikibook is an example of these, where you can add a series of pages linked as a sequence. Other great extensions are more powerful editors, media managers, attachments, rss feeds. If you want to contribute to the community, install a copy of the wiki and run test on new possible extensions that the community could benefit from it. This is another way to contribute to the community by becoming the wiki guy.
Ideas, thoughts and Free Software 