How GitHub Uses GitHub to Document GitHub • Hacker News Board

Re: How GitHub Uses GitHub to Document GitHub

#51

Post by conorgil145 » Wed, Jan 07, 2015, 10:42 PM UTC

zeroDivisible wrote: post #49

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…

If you like swagger, I'd also check RAML - http://raml.org/ I found it recently, but it looks quite interesting.

Thanks for suggesting this. I glanced over the home page and I am definitely adding it to my list of projects to explore. It claims to support many of the features that I am looking for and it will be fun to kick the tires!

Re: How GitHub Uses GitHub to Document GitHub

#52

Post by conorgil145 » Wed, Jan 07, 2015, 10:53 PM UTC

crdoconnor wrote: post #46

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

> I wish people would stop viewing documentation as an additional formal step needed to 'package' the software (a nasty chore) and instead viewed it as an exercise in communicating as clearly and concisely as possible what the project is about and how it works.

Yes 1000x. One of the first things I do when evaluating a new project is read the docs and tutorials.

A glossary for each project would also be super useful. I have also run into the issues that you outline (one term to many definitions and vice versa). Do you think the glossary would help solve that by forcing folks to rename things to have clearer terms (if one is already used in the glossary, for example) or do you think that it is just a barrier for some developers to even create the glossary in the first place (out of sight, out of mind mentality).

Would you keep the glossary in git (or similar) so that it versions along with the code? It could be a required part of a code review to make sure that reasonable terms and/or acronyms introduced in a PR are added to the glossary.

Re: How GitHub Uses GitHub to Document GitHub

#53

Post by conorgil145 » Wed, Jan 07, 2015, 10:58 PM UTC

NhanH wrote: post #40

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…

Isn't what you describe (documentation first, then code) basically a poor man version of literate programming ;) ?

I wasn't familiar with the term, but a quick search reveals Literate Programming on Wikipedia [1]. I assume that is what you were referencing. I skimmed the summary of the article and it sounds interesting (and similar to what I'm describing).

[1] https://en.wikipedia.org/wiki/Literate_programming

Re: How GitHub Uses GitHub to Document GitHub

#54

Post by dang » Wed, Jan 07, 2015, 11:59 PM UTC

bcRIPster wrote: post #43

scrollaway wrote: post #35

Earlier quoted context omitted.

If everyone was already thinking it, what makes you think they want to see it in the comments?

Well, 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.

Comment scores decrease when users downvote them. Moderators don't give comments negative scores.

Re: How GitHub Uses GitHub to Document GitHub

#55

Post by bcRIPster » Thu, Jan 08, 2015, 4:55 AM UTC

dang wrote: post #54

bcRIPster wrote: post #43

Earlier quoted context omitted.

Well, 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.

Comment scores decrease when users downvote them. Moderators don't give comments negative scores.

I now understand about how the system works after someone else explained. But, thank-you for the feedback.