Writing documentation can be a serious pain. So the oft taken path is to not write anything. Recently, I was exploring menu options in Eclipse and noticed the WikiText option. I must have been hiding under a rock because I haven’t noticed how nice WikiText is nor where it is applicable.
WikText is a structured language that is easily readable by humans and is pretty easy to parse. As an example this is how you write a h1:
h1. Main heading
It really couldn’t be any more simple than that. Similar markup exists for a larger part of HTML as well. Here are a few more examples:
*this creates bold text* __italic text__ #Numbered list item 1 #Numbered list item 2 *Bulleted list item bc. Block Code in here
An easy to use markup language isn’t that interesting on it’s own IMO, but when it’s natively supported by your tooling things get a lot more useful.
So typing something like this in Eclipse:
Generates something like this:
Even outside of Eclipse, I find this useful as many sites will parse your .textile files. Outside of wiki sites, I think the most notable would be git hub. If you have a README.textile they will parse it and generate the HTML for your project page based off of it.
The Eclipse documentation here talks more about the capabilities but I think the above are the most important (especially if your like me and didn’t know about it).