How GitHub Uses GitHub to Document GitHub

http://zachholman.com/talk/how-github-uses-github-to-build-g...

I have always been interested in documentation and its order in the priority list of tasks which a development team has to tackle. It is not an original observation that documentation is critically important to the success of a project/code-base and yet it is often the last artifact produced (and many skip it altogether). I have recently been extremely interested in the idea that documentation should be moved to the top of the priority list and, rather than being a duplicative post-processing step, should be the "ground-truth" for generating lots of the follow on artifacts. For example, write API documentation first and use that to generate client side libraries, an API test suite, and server boiler plate code/skeleton.

In my search for existing projects and approaches, I came across many interesting things.

Swagger: https://helloreverb.com/developers/swagger

API Doc: http://apidoc.me/doc/gettingStarted

Slate: https://github.com/tripit/slate

Write the Docs: http://docs.writethedocs.org/

It was very interesting to read this GitHub post because they presented yet another approach to treating documentation as a first class citizen with different methods to write docs, host docs, and keep the docs updated.

I recently updated the API docs at my workplace to use the Slate tool I referenced above. We manually write docs in a Markdown file, manually use Slate to compile the MD file into HTML, and then manually deploy it to our host. This is approach is incredibly basic and non-scalable, but is light years better than what we had previously, which was API docs directly in the repo's README file.

I hope to learn more about the projects listed above (and many others!) as I explore different approaches for treating docs as a first class citizen and pick the approach which meets the requirements of my current team.

[EDIT] I am also anxiously awaiting a beta invite for http://readthedocs.com