News for hackers. Stuff that matters.
Re:How GitHub Uses GitHub to Document GitHub by jondot on Tuesday January 06, 2015 @04:08PM (#8847138)
I'm planning to build a stack for internal company domain knowledge, and I've been thinking about middleman (http://middlemanapp.com) instead of Jekyll.

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)

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 :)

Re:How GitHub Uses GitHub to Document GitHub by technoweenie on Tuesday January 06, 2015 @05:24PM (#8847507)
I think the main take-away with this post is that static sites for docs are awesome. GitHub uses [nanoc](http://nanoc.ws/) for the [API documentation](https://developer.github.com/).

The only downside of hosting static text on GitHub Pages without Jekyll is that you have to push the generated HTML too.

Re:How GitHub Uses GitHub to Document GitHub by gjtorikian on Tuesday January 06, 2015 @06:35PM (#8847900)
> which makes less contention for the probably huge conref file

We're planning on splitting up the conref files by section. So for example, we'd get a separate conref file for Pages, one for UI stuff, one for Enterprise, etc. My only compliant with partials is that it's one piece of content per file, but it's a trade-off vs one file with several conrefs (gotta CTRL-F for that text you want to change).

Re:How GitHub Uses GitHub to Document GitHub by conorgil145 on Tuesday January 06, 2015 @07:30PM (#8848109)
Ironcially, just earlier today my co-worker and I were also discussing plans to setup a domain knowledge service internally. He came across a tool called Raneto [1] which looks very promising, but we have not had time to play with it extensively yet. Perhaps it could be useful for your use-cases too.

[1] http://raneto.com/

Re:How GitHub Uses GitHub to Document GitHub by mtmail on Tuesday January 06, 2015 @04:09PM (#8847144)
you probably mean https://middlemanapp.com/
Re:How GitHub Uses GitHub to Document GitHub by jondot on Tuesday January 06, 2015 @04:13PM (#8847169)
Much thanks, fixed :)
Re:How GitHub Uses GitHub to Document GitHub by nahname on Tuesday January 06, 2015 @04:43PM (#8847323)
Middleman has almost no automated testing suite. Important to note if you are going to invest in something.