Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How GitHub Uses GitHub to Document GitHub

github.com

Post reply on HN
Print view View original

21–30 of 55 posts

Re: How GitHub Uses GitHub to Document GitHub

#21

Post by gkoberger »

conorgil145 wrote: post #16
codezero wrote: post #10

Earlier quoted context omitted.

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.

We aren't using Swagger (although we someday plan on supporting it); shoot us an email (support@readme.io) if we can help you get set up!

Re: How GitHub Uses GitHub to Document GitHub

#22

Post by gjtorikian »

lapfi wrote: post #20
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 test…

I wholeheartedly agree with everything above. Two additional and related thoughts:

1. The original documentation tool I wrote for Atom, Biscotto, kept track of the number of undocumented classes / methods: https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92ae... . It was hooked up to CI, and if the count fell below a certain threshold, the test failed.

2. Right now, we're exploring into working with JSON schema as a means of providing both testing validation and accurate documentation. If the schema says "This REST method expects a parameter of this type," it becomes very easy to write a test to enforce that behavior; documentation can be easily generated from it; and of course your production code is safer for it.

I'm a huge fan of introducing more cross-overs between testing and documentation. I think a lot of time is spent on "clever" (and subjective) validations like http://www.hemingwayapp.com/, but not enough time is spent on basic content checks. It's very easy to drift code, tests, and docs apart. We need to start thinking about all three of them working together.

Re: How GitHub Uses GitHub to Document GitHub

#23

Post by conorgil145 »

lapfi wrote: post #20
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 test…

That is an interesting idea.

I do like the idea of starting by writing docs because they are very lightweight and it forces you to think through the design of the API. For example, "the params on that route don't look correct" or "this is really difficult to explain, so I think we just over complicated this end point. Let's make it simpler".

One could make the TDD argument that writing tests first would accomplish the same thing, but I think tests are much heavier than docs because certain routes could have dependencies and other similar gotchas. For example, a route may require authentication so you either need to have a fake auth token in the test DB or you need to have your test first obtain an auth token via the API and then hit the end point you really want to test.

If you start by writing docs in something like Swagger, then it should be straight forward to generate API tests from those docs (given, you will still have some gotchas like in the authentication scenario, but if you are generating the tests, then you solve that issue once in your test generator and then the boiler plate is created for you). For example, if you add a required param to a route, you first update your docs to define this new require param and then re-generate the automated test suite. A generated test suite like that could be used for TDD purposes to develop against.

Can you expand on your idea of generating docs from tests? Your tool sounds very interesting. Is it open source for me to look at? If not, how did you have to format/structure your tests so that you knew what information to include in the docs? How did the generation work?

Re: How GitHub Uses GitHub to Document GitHub

#24

Post by rpgmaker »

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…

Whatever happened to that "git-based" document format Linus said he was going to work on?

Re: How GitHub Uses GitHub to Document GitHub

#25

Post by gjtorikian »

afarrell wrote: post #19

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

> 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

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.

Re: How GitHub Uses GitHub to Document GitHub

#26

Post by gjtorikian »

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…

> 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

#27

Post by conorgil145 »

gjtorikian wrote: post #22
lapfi wrote: post #20

Earlier quoted context omitted.

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

I wholeheartedly agree with everything above. Two additional and related thoughts: 1. The original documentation tool I wrote for Atom, Biscotto, kept track of the number of undocumented classes / methods: https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92ae... . It was hooked up to CI, and if the count fell below a certain threshold, the test failed. 2. Right now, we're exploring into working with JSON schem…

I could not agree more strongly that working on code, docs, and tests as a single unit is an excellent approach to development. I think the best way to convince most developers of doing this is to create tools which make it as automated as possible. If using a tool actually makes their lives easier to accomplish something they already do (write tests? write docs?) and they get the other for free, then that is a huge selling point.

I had a similar idea about using JSON Schema to validate my API. However, a few issues that I thought of and a few I discovered while researching:

1) I am not aware of a decent JSON Schema editor. It has been on my wishlist/TODO list for a looong time to write one myself which has similar capability to something like Oxygen for XML [1], but I have not had the time. Do you plan to write and update the JSON Schema by hand?

2) I have not researched them in great detail yet, but Swagger [2] and API Doc [3] seem to have already defined something similar to what I had in mind with JSON Schema. Have you looked into those tools yet?

[1] http://www.oxygenxml.com/index.html [2] https://helloreverb.com/developers/swagger [3] http://apidoc.me/doc/gettingStarted

Re: How GitHub Uses GitHub to Document GitHub

#28

Post by gjtorikian »

bostonvaulter2 wrote: post #17

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

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

Re: How GitHub Uses GitHub to Document GitHub

#29

Post by conorgil145 »

gkoberger wrote: post #21
conorgil145 wrote: post #16

Earlier quoted context omitted.

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.

We aren't using Swagger (although we someday plan on supporting it); shoot us an email (support@readme.io) if we can help you get set up!

Thanks for the info! I have many questions about your tool, but if the answer is "go check it out via a free account!" then just tell me that and I'll get around to it :)

- Were you influenced by Swagger at all? Did you exist before/after?

- Do you expose any schema that developers can modify via an API or similar? Do you have an internal schema that all docs follow?

- I edited my original comment to include Read the Docs [1]. Are you familiar with that service (it is in private beta)? What are some advantages of using ReadMe instead of Read the Docs?

[1] http://readthedocs.com

Re: How GitHub Uses GitHub to Document GitHub

#30

Post by gjtorikian »

conorgil145 wrote: post #27
gjtorikian wrote: post #22

Earlier quoted context omitted.

I wholeheartedly agree with everything above. Two additional and related thoughts: 1. The original documentation tool I wrote for Atom, Biscotto, kept track of the number of undocumented classes / methods: https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92ae... . It was hooked up to CI, and if the count fell below a certain threshold, the test failed. 2. Right now, we're exploring into working with JSON schem…

I could not agree more strongly that working on code, docs, and tests as a single unit is an excellent approach to development. I think the best way to convince most developers of doing this is to create tools which make it as automated as possible. If using a tool actually makes their lives easier to accomplish something they already do (write tests? write docs?) and they get the other for free, then that is a huge…

> Do you plan to write and update the JSON Schema by hand?

Currently, yes, unfortunately. ;____; We've talked about doing it in an intermediate format, like YAML, which is slightly less painful, but....ugh. Years ago I wrote a very badly-coded-but-essentially-functional tool called Panino, which converted Markdown-to-JSON: https://github.com/gjtorikian/panino-docs/tree/master/lib/pa....

I see that some people have picked up on that and ran along with it, too: https://github.com/apiaryio/mson. So there might be something there to explore.

2. I've never looked into either. I know Swagger is used by several companies, like Twitter, but API Doc is new to me.

Post reply on HN