How GitHub Uses GitHub to Document GitHub • Hacker News Board

Re: How GitHub Uses GitHub to Document GitHub

#11

Post by masklinn » Tue, Jan 06, 2015, 9:20 PM UTC

Animats wrote: post #5

Github'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".

> 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

Re: How GitHub Uses GitHub to Document GitHub

#12

Post by bcRIPster » Tue, Jan 06, 2015, 9:28 PM UTC

bcRIPster wrote: post #2

Yo dawg!

Awe, negative points? Really? You know you were thinking it when you saw the link title.

Re: How GitHub Uses GitHub to Document GitHub

#13

Post by forsaken » Tue, Jan 06, 2015, 9:34 PM UTC

conorgil145 wrote: post #6

I 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 extrem…

Another option is Read the Docs, which is how we host the Write the Docs docs: http://docs.readthedocs.org/en/latest/ -- It's basically the above workflow that GitHub describes, but with Sphinx (http://sphinx-doc.org/) -- which is a mature and powerful documentation system.

Re: How GitHub Uses GitHub to Document GitHub

#14

Post by nahname » Tue, Jan 06, 2015, 9:43 PM UTC

jondot wrote: post #7

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 b…

Middleman has almost no automated testing suite. Important to note if you are going to invest in something.

Re: How GitHub Uses GitHub to Document GitHub

#15

Post by technoweenie » Tue, Jan 06, 2015, 10:24 PM UTC

jondot wrote: post #7

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 b…

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

#16

Post by conorgil145 » Tue, Jan 06, 2015, 10:25 PM UTC

codezero wrote: post #10

conorgil145 wrote: post #6

I 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 extrem…

You may also want to check out Readme: https://readme.io/

Thanks 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.

Re: How GitHub Uses GitHub to Document GitHub

#17

Post by bostonvaulter2 » Tue, Jan 06, 2015, 10:25 PM UTC

Isn't the three second load page they list on the slow side?

Re: How GitHub Uses GitHub to Document GitHub

#18

Post by conorgil145 » Tue, Jan 06, 2015, 10:29 PM UTC

forsaken wrote: post #13

conorgil145 wrote: post #6

I 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 extrem…

Another option is Read the Docs, which is how we host the Write the Docs docs: http://docs.readthedocs.org/en/latest/ -- It's basically the above workflow that GitHub describes, but with Sphinx ( http://sphinx-doc.org/ ) -- which is a mature and powerful documentation system.

I forgot to mention that, but it is already on my list of things to investigate. I came across readthedocs.com in the last few months (probably on HN) and sent a passionate email requesting access to the private beta. I haven't been selected yet, but I am anxiously waiting to try it out.

How would you say that readthedocs.com differs from the tool mentioned in a sibling comment (Readme: https://readme.io/)?

Re: How GitHub Uses GitHub to Document GitHub

#19

Post by afarrell » Tue, Jan 06, 2015, 10:39 PM UTC

I'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.

Re: How GitHub Uses GitHub to Document GitHub

#20

Post by lapfi » Tue, Jan 06, 2015, 10:44 PM UTC

conorgil145 wrote: post #6

I 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 extrem…

I always thought it would be a good idea to generate API documentation from tests. Kind of the same idea you have but the other way around.

The problem I used to have is that if you write your documentation by hand it tends to get out of sync with the code. You make a quick change to the code and forget to update the docs. After a while it's a mess unless you stay vigilant.

But if you generate documentation from tests they can't get out of sync. The example output that gets written to the docs comes from the application so it can't be wrong. And if a test fails, documentation doesn't get written. It also forces you to write tests which is a good thing. If you don't, you don't have docs.

I don't know if there are tools like this. I created one for Ruby/Rack apps that I have used in some of my projects. I think this approach works pretty well.