Wednesday, December 7, 2011

Github Pages

I'm a huge fan of Github. Pull requests are the best innovation since the idea behind open source was created.

For one of my projects hosted on Google Code, I was recently asked to move it to Github so that someone could submit pull requests more easily. I happily complied because of how much I love Github.

As part of this move, I decided to finally explore Github Pages in order to publish the nicely formatted documentation of my project. I was thinking they'd be as great as pull requests, and after an hour of reading the documentation and installing everything, I was terribly disappointed.

The main issue is that it uses a site generation tool called Jekyll. While this tool is generally ok, it has a quite a few major failings as a product for Github.
  • It is clearly a product of Not-Invented-Here syndrome. How many static website generators does this world need? Why did you feel the need to invent yet another one? Hell, I don't even want a static website generator, I just want to write some documentation.
  • I don't want 50 different options for generating content. Just give me Markdown. I don't even want 2 different types of Markdown. Just give me the one that works best, as default.
  • By default, it comes with nothing to help you design a site full of great looking documentation. Even just a default template setup would suffice. Some people have tried to create some helper projects, but they all have terrible UI and they all seem somewhat abandoned.
  • It requires me to become an expert in this tool. I have to install a bunch of random software, learn configuration files, learn a specific file layout. All I want to do is write some documentation that looks nice!
  • It was basically created for publishing blogs. Why is this being promoted as GH Pages? It seems rather absurd for a source code repository to provide a tool for publishing blogs, but not a tool for publishing great documentation.
Back over on Google Code, I just create some wiki pages, link them together with a table of contents (also a wiki page) and point at a specific url. Everything just works and looks great.

Github, please fix this!

4 comments:

Michael Hart said...

Er... Why don't you just use the wiki provided by GitHub then?

Plenty of GitHub projects just use the wiki for documentation.

Jon Scott Stevens said...

Because, correct me if I'm wrong, the wiki on GH doesn't provide an interface to make your documentation look good.

Take a look at this:

http://code.google.com/p/jmxtrans/wiki/IntroductionToJmxTrans?tm=6

It is all driven by pages checked into the wiki source directory. If GH has a nice interface layered on top of the wiki, then I'd be stoked. This doesn't cut it:

https://github.com/lookfirst/jmxtrans/wiki

thanks,

jon

Walter Cruz said...

put a .nojekyll file, generate your html voi-la :)

Jon Scott Stevens said...

Walter, you get a downvote for a pointless reply.