5 ms·
How GitHub Uses GitHub to Document GitHub
- bcRIPster 12y agoYo dawg!
- bcRIPster 12y agoAwe, negative points? Really? You know you were thinking it when you saw the link title.
- scrollaway 12y agoIf everyone was already thinking it, what makes you think they want to see it in the comments?
- bcRIPster 12y agoWell, given that I imagine only mods can set negative value to a post, I'm going to infer that the mods didn't like seeing it in the comments. You know, sometimes it's ok to find humor in things.
- stefs 12y agoyes, but it's still not in any way adding to the discussion.
- bcRIPster 12y agoWho's to say, it got blasted away immediately. Whatever.
- SEJeff 12y agoThis title alone is gitception!
- myared 12y agoIf you like this, also see the talk titled "How Github uses Github to build Github". http://zachholman.com/talk/how-github-uses-github-to-build-github/ http://zachholman.com/talk/how-github-uses-github-to-build-g...
- bcRIPster 12y agoWelcome to the downmod train brother. Seems the two of us are being persecuted for trying to add some levity amongst the Hipsters.
- Animats 12y agoGithub's convention that web pages for a project are in a different branch of the same project is kind of strange. Also, those things they call "conrefs" are just "macros".
- masklinn 12y ago> Github's convention that web pages for a project are in a different branch of the same project is kind of strange. It does have the advantage of 0-configuration 0-conflict. But because it namespaces through the branch, if you're using the repository for something other than just the pages you can't have the gh-pages simply follow/trail master unless you want a bunch of site crap at the root of your repository, and interacting with both code and documentation at the same time is more painful than it needs be. > Also, those things they call "conrefs" are just "macros". Macros have a wider implied range of behavior, possibly completely arbitrary. A content reference attribute is just a placeholder or a very small textual include[0] (XML calls them "named entities", rST calls them "substitutions") [0] usually not of a complete document
- gjtorikian 12y agoI think a macro implies something that can be executed, and (rightly) ought to cause security-minded folks to double-take. Conref isn't something we invented, it's straight out of DITA: http://dita.xml.org/arch-conref http://dita.xml.org/arch-conref
- snogglethorpe 12y ago> I think a macro implies something that can be executed That isn't true... Traditionally a macro just refers to a substitution, maybe (but not necessarily) with parameter replacement, rescanning, etc. I'd say that lisp-style macros which can execute arbitrary code are actually rather rare historically....
- conorgil145 12y agoI personally found this write up extremely interesting and exciting. 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 https://helloreverb.com/developers/swagger API Doc: http://apidoc.me/doc/gettingStarted http://apidoc.me/doc/gettingStarted Slate: https://github.com/tripit/slate https://github.com/tripit/slate Write the Docs: http://docs.writethedocs.org/ 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 http://readthedocs.com
- codezero 12y agoYou may also want to check out Readme: https://readme.io/ https://readme.io/
- conorgil145 12y agoThanks for suggesting another tool to look into! I only glanced at their homepage, but it looks like they may be using Swagger under the hood because some visual elements are similar and the functionality is also similar. It does appear to have many of the features that I am looking for, so it definitely warrants further investigation.
- jondot 12y agoI'm planning to build a stack for internal company domain knowledge, and I've been thinking about middleman (http://middlemanapp.com 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 :)
- mtmail 12y agoyou probably mean https://middlemanapp.com/ https://middlemanapp.com/
- jondot 12y agoMuch thanks, fixed :)
- nahname 12y agoMiddleman has almost no automated testing suite. Important to note if you are going to invest in something.
- technoweenie 12y agoI think the main take-away with this post is that static sites for docs are awesome. GitHub uses [nanoc](http://nanoc.ws/ http://nanoc.ws/) for the [API documentation](https://developer.github.com/ 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.
- gjtorikian 12y ago> 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).
- bostonvaulter2 12y agoIsn't the three second load page they list on the slow side?
- gjtorikian 12y agoI wasn't super thrilled with it either, until I dug in and discovered that it's the global average. We have a ton of international and mobile traffic, which factors into this sum: 1. United States (average load: 1.97 s) 2. United Kingdom (average load: 2.29 s) 3. India (average load: 7.48 s) 4. China (average load: 12.11 s) Average load of these countries is 6 seconds, which seems absolutely horrid...until I tell you that the US has about seven times more traffic than the UK. I didn't want to fudge the graph and take out those slow outliers--the truth's the truth.
- afarrell 12y agoI'm curious, how they write internal-facing documentation and how that effects the development experience for new github engineers. 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.
- gjtorikian 12y ago> I'm curious, how they write internal-facing documentation and how that effects the development experience for new github engineers. I wish I could show up a sample, but I can't, because it's internal. ;) Honestly, I think a lot of the engineering documentation started organically. When you have a small team working on a feature, it's difficult to scale explanations to the rest of the company. One day someone sits down and starts writing all their thoughts out in Markdown, and just checks it into a docs folder. That's it. It's easy-to-read, short on code, and usually full of ASCII, like this: https://i.imgur.com/KTbyhyq.png https://i.imgur.com/KTbyhyq.png Writing documentation is the best way to get outside contributors involved with minimal investment on your part. It also forces you to try and explain what you've built. If you can't pretend to go back and look at things like a beginner, grab someone unfamiliar with the project, and have them describe to you what they would expect, and how they think they should proceed. They may be able to provide you with insights on what needs to be described.
- forrestthewoods 12y agoGitHub 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.
- waldir 12y agoUnfortunately the repository (as suggested by the screenshot[1]) seems to be private: https://github.com/github/help-docs https://github.com/github/help-docs I assume that's because they may be documenting upcoming features before they are announced. 1. https://cloud.githubusercontent.com/assets/64050/5449088/7adf83be-84a3-11e4-8c41-1b3448a2f7df.png https://cloud.githubusercontent.com/assets/64050/5449088/7ad...
- fidz 12y agoI wonder if they host everything on their own site (Github.com) or their own Github Enterprise site, which is inaccessible from outside network.