Structuring github pages

Question

If you have a site called http://username.github.com and a project called projectname, do you

1. use http://github.com/username/projectname/tree/gh-pages to a) mirror your master branch, or b) create a webpage describing the project (to be reflected in http://username.github.com/projectname), or
2. not have a http://github.com/username/projectname/tree/gh-pages branch at all?

Answer 1

What I understand of gh_pages as presented in pages.github.com, is that it is for:

• creating a separate branch: your repo has now two roots (one for master and all the dev branches, one for gh_pages for GitHub published content).
  The root for gh_pages branch has a special treatment when managed by GitHub.
• "publish content to the web": and that can be any content you want.
  So if you don't need a full space for documentations, you can just go with a readme.md file or an index.html page ("user page").
  help.github.com itself is organized as documents within a gh_pages branches.

Answer 2

I usually don't have a project page at all (most of my public github projects are mirrors of other open-source projects), but on the ones where I do, I have a web page describing the project.

Although I just had an idea: might be neat to make a project's gh-pages branch contain a highlighted, hyperlinked version of your code (run it through Doxygen and have it only generate cross-referenced source instead of documentation, for example).