I personally found this write up extremely interesting and exciting.<p>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.<p>In my search for existing projects and approaches, I came across many interesting things.<p>Swagger: <a href="https://helloreverb.com/developers/swagger" rel="nofollow">https://helloreverb.com/developers/swagger</a><p>API Doc: <a href="http://apidoc.me/doc/gettingStarted" rel="nofollow">http://apidoc.me/doc/gettingStarted</a><p>Slate: <a href="https://github.com/tripit/slate" rel="nofollow">https://github.com/tripit/slate</a><p>Write the Docs: <a href="http://docs.writethedocs.org/" rel="nofollow">http://docs.writethedocs.org/</a><p>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.<p>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.<p>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.<p>[EDIT] I am also anxiously awaiting a beta invite for <a href="http://readthedocs.com" rel="nofollow">http://readthedocs.com</a>
I'm curious, how they write internal-facing documentation and how that effects the development experience for new github engineers.<p>Source diving through open source libraries, I've often wished for a "spelunker's guide": a text file laying out where things were and what I should read first to build a mental model I could use in understanding the rest of the source. I'm currently trying to figure out what the best way is for someone to write a spelunker's guide, especially if they've forgotten what it's like to be a beginner.
I'm planning to build a stack for internal company domain knowledge, and I've been thinking about middleman (<a href="http://middlemanapp.com" rel="nofollow">http://middlemanapp.com</a>) instead of Jekyll.<p>Middleman has impressive workflows and markdown processing (I'm guessing parallel to that of the Github/Jekyll solution or better).
Also conrefs can be implemented by simple partials (which makes less contention for the probably huge conref file)<p>Though I have to be convinced by trying the Github/Jekyll stack, this does open my mind regarding Jekyll 2.0. I'm happy to see Github tell us their Jekyll story :)
Unfortunately the repository (as suggested by the screenshot[1]) seems to be private: <a href="https://github.com/github/help-docs" rel="nofollow">https://github.com/github/help-docs</a><p>I assume that's because they may be documenting upcoming features before they are announced.<p>1. <a href="https://cloud.githubusercontent.com/assets/64050/5449088/7adf83be-84a3-11e4-8c41-1b3448a2f7df.png" rel="nofollow">https://cloud.githubusercontent.com/assets/64050/5449088/7ad...</a>
Github's convention that web pages for a project are in a different branch of the same project is kind of strange.<p>Also, those things they call "conrefs" are just "macros".
GitHub Pages is one of the most shocking hacks I've ever come across. Not the worst mind you, just the most shocking. Most of GitHub is clean and good. But making a magic gh-pages branches is simply horrific. I'm still somewhat dumb founded that's the best method they could come up with.