awesome github feature: no excuse for not having good docs anymore

I am a documentation fanatic. The way some people get all excited about how code isn’t finished until there are tests (which I agree with generally): I think code isn’t finished until there are docs, and until you’ve updated the docs to match your changes.

It’s just not usable by other developers (including future you) unless there are docs — both inline docs, including of the sort that can be autogenerated into api docs with javadoc or rdoc ; and also often there is need for some narrative overview architectural docs too.

Now, github is a great place to host a project. And the way github renders markdown as html makes it pretty great for viewing docs too.

I like the way github’s project landing page is a source tree and a README. That’s exactly right, I don’t want the source tree hidden, because when I’m investigating someone elses project, or when I’m trying to figure something out about a project i’m already using, I want to be able  to navigate and view the source in a web browser very quickly.

YES, the source is important documentation in itself, but seldom is sufficient documentation on it’s own. Usually you at least need a README.

And then github gives you the README right below. Markdown readme rendered into HTML, so easy on the eyes on the brain. Great, perfect!

And then in some projects, the README keeps growing…. and growing… and growing. And you might think, gee, why not move some of this to some other files, if a source code file shouldn’t be 1000 lines long, a README prob shouldn’t be either.

The problem was that github did not support relative hyperlinks in README and other rendered markdown/markup.  So you couldn’t link out from the README to another file in your source, in a context-specific way. Sure, you could link out to your wiki — but wiki isn’t versioned along with source code, and you want to link to the version of the docs that go along with the exact snapshot of the source repo you’re looking at. Sure, you could link out using absolute URL hyperlinks — but same problem, you’re always linking to master, when you want to link to the file in the same snapshot the reader is looking at the README in.

You might think relative links would ‘just work’. They kind of do with hyperlinks in generated rdoc/markdown you generate on your local machine. But because of the way github’s infrastructure works, the relative path between a README and the rest of the source tree changes depending on whether you’re looking at project landing page, a branch tip, a tag, or a SHA hash snapshot. So they didn’t.

But, finally, github fixed things so relative links work. Hooray. 

So, yeah, you can split out your docs into multiple files in `./docs/`.  And have those links work whether you’re viewing in github, or in generated rdoc on, or generated rdoc on your local machine, or anywhere.

The other huge benefit this has is that you can link from a README to a source file now too.  When discussing a class, you can link to the source of the class. When providing an overview of a feature that’s covered in more depth in inline rdoc/javasdoc docs, you can link to it. Helping you avoid duplication of documentation between source files and doc files (DRY is just as important in docs as in source, for the same reasons), and integrating your documentation files and your source control.

This is going to make it so much more efficient to maintain good docs for projects hosted on github, and to maintain docs that are properly snapshotted with the source snapshot they refer to, instead of wiki docs where you never can tell what version of the source they refer to (last release? master?).

Hooray. ndushay says “I am not your mother. Write your test code.” I say, I ain’t your daddy either,  write your documentation.



((My next github doc fantasy? The syntax highlighter for ruby could realize when there was embedded markdown/rdoc in top-of-class and top-of-method comments, and render them formatted)

One thought on “awesome github feature: no excuse for not having good docs anymore

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s