It seems a lot of people crank about writing documentation, so I wasn’t looking forward to writing some for Wikiwhat, but I knew it was important, not just to for the sake of doing it, but because as the n00biest of n00bs, I wanted someone with no idea of how things work to be able to use our gem easily, on the off chance anyone would want to use it. However, it turned out that writing the documentation for Wikiwhat was way easier than writing lab reports or manuscripts, and I had a lot of fun doing it.

If you have never used markdown before, this page is a good summary of the basics of markdown syntax.

Use Mou

Mou is a great Markdown editor that shows you what you markdown will look like as you are writing it. I found this really helpful as I was experimenting with the different formatting options in Markdown. It can also do a bunch of other fancy things. The one catch is that it does not currently support Github-flavored Markdown, so Github-specific Markdown will not be rendered correctly. To check anything Github-specific, you will have to check out one of the Github-flavored markdown previewers.

Make Internal Links

This one tripped me up for a while, but it’s secretly really easy.

[Google](http://google.com)

gives a link to google like so:

Google

But I wanted to make links within a page, so someone reading the README could jump to the section they wanted to read without scrolling though the whole page. Github makes this easy by turning any header into an internal anchor point!

[Usage](#usage)

will make a link to the ‘Usage’ header lower down on the page. If the header text is more than one word, the text is converted to all lowercase with dashes (-) replacing the spaces, like so:

[A Header With Multiple Words](#a-header-with-multiple-words)

Specify the language

You will probably want to have code examples in your README. Github will syntax-highlight them for you correctly if you tell it what language it is. When you make a code fence, specify the language immediately after the first ‘fence’ for correct syntax hilighting.

```ruby
<ruby code>
```