Thoughts/Summary for Writing Documentations

Just another day, another developer asked me for some advice on writing documentations. Here were the four tips I gave him:

1. Try to extract the code you want to document on to a method/class, use the method name /class name as the documentation.
2. Add comments for hacks or other things that cannot be applied by 1, also add the comments into the commit message for this change.
3. Use test/spec examples as usage explanations if you want examples on how to use your code.
4. Use yard/rdoc if you want to export your documentations to other formats (e.g. html).