AWS documentation is now open source and on GitHub • Hacker News Board

Re: AWS documentation is now open source and on GitHub

#61

Post by kartan » Wed, Mar 14, 2018, 6:02 AM UTC

quadrature wrote: post #10

jjeaff wrote: post #3

Brilliant. Let unpaid volunteers fix and update the documentation for your proprietary systems so you don't have to pay someone to do it. Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?

Well as a user of Amazon you have a vested interest in the documentation being correct. It is what other members of your team and organization will be referring to. Having it on GitHub will also add additional context around changes in the form of PRs, Issues and the commit history.

> Well as a user of Amazon you have a vested interest in the documentation being correct.

As a Walmart customer it's in my best interest that the aisles are clean. But I will doubt the legality to ask customers to clean the aisles so they don't need to pay for a cleaning service. Actually using volunteers to replace employees is kind of illegal.

Re: AWS documentation is now open source and on GitHub

#62

Post by fergie » Wed, Mar 14, 2018, 6:08 AM UTC

samschooler wrote: post #33

always_good wrote: post #22

Earlier quoted context omitted.

Just think of all the uncompensated value you've given Y Combinator every time you've left a quality comment on their forum.

Then again, Y Combinator makes no direct money off HN. AWS’ docs, if they are quality directly impacts their profit because more people can use their services more easily.

Hacker News is the textbook example of a highly successful content marketing platform for software engineers. Second only to Joel on Software.

Re: AWS documentation is now open source and on GitHub

#63

Post by confounded » Wed, Mar 14, 2018, 6:48 AM UTC

justicezyx wrote: post #45

samschooler wrote: post #33

Earlier quoted context omitted.

Then again, Y Combinator makes no direct money off HN. AWS’ docs, if they are quality directly impacts their profit because more people can use their services more easily.

AWS does makes no direct money off documentations either. Engineers generally have a natural tendancy to fix things, and documentaitons are worth fixing. And it also helps their future work.

I think there’s a reasonable argument that documentation is an integral part of usable software.

Re: AWS documentation is now open source and on GitHub

#64

Post by INTPenis » Wed, Mar 14, 2018, 6:55 AM UTC

jjeaff wrote: post #3

Brilliant. Let unpaid volunteers fix and update the documentation for your proprietary systems so you don't have to pay someone to do it. Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?

Heh that's a very cynical view and it speaks to me. But my first thought was that this will make me choose AWS over alternatives because I've found the docs for GCP very confusing and sometimes outdated.

But regarding why people would bother helping. Well I guess it's the same reason some people help out with wikipedia. Not all of them do it for ideological reasons. Some are just very nitpicky and anal.

Re: AWS documentation is now open source and on GitHub

#65

Post by d_burfoot » Wed, Mar 14, 2018, 7:14 AM UTC

Gah, choke, barf.

Crowd-sourcing is not the right way to document a big complex software suite.

The right way is to use special software to compile or extract the documentation from the underlying source code. The documentation generator should be conceptually similar to a Jupyter Notebook or a Mathematica Computable Document.

Furthermore, the documentation generator should run actual code that throws an error if there's a mistake. For example, in this document:

https://github.com/awsdocs/aws-cli-user-guide/blob/master/do...

The CLI operations should be lifted from some other file, and that other file should get run as a test by a CI tool, so that when there's a change to the CLI, it's automatically flagged for correction.

Re: AWS documentation is now open source and on GitHub

#66

Post by jeffbarr » Wed, Mar 14, 2018, 7:37 AM UTC

shady-lady wrote: post #2

I would reject that PR. Something like that change should have a message explaining why that change is proposed. Unfortunate that the blogpost itself can't be forked :p

I wrote it -- do I need to make a fix??

Re: AWS documentation is now open source and on GitHub

#67

Post by csomar » Wed, Mar 14, 2018, 7:44 AM UTC

samschooler wrote: post #33

always_good wrote: post #22

Earlier quoted context omitted.

Just think of all the uncompensated value you've given Y Combinator every time you've left a quality comment on their forum.

Then again, Y Combinator makes no direct money off HN. AWS’ docs, if they are quality directly impacts their profit because more people can use their services more easily.

Indirect money as in brand/capital is still wealth. You have contributed to that creation of wealth.

Re: AWS documentation is now open source and on GitHub

#68

Post by rhizome » Wed, Mar 14, 2018, 7:48 AM UTC

confounded wrote: post #63

justicezyx wrote: post #45

Earlier quoted context omitted.

AWS does makes no direct money off documentations either. Engineers generally have a natural tendancy to fix things, and documentaitons are worth fixing. And it also helps their future work.

I think there’s a reasonable argument that documentation is an integral part of usable software.

Not only is there a reasonable argument, a major chunk of Fred Brooks' "The Mythical Man Month" is about documentation being the entire spec and that software should not do anything that isn't in its actual documentation. Write the documentation, then hand it off to the developers to implement.

Re: AWS documentation is now open source and on GitHub

#69

Post by jve » Wed, Mar 14, 2018, 7:53 AM UTC

ioddly wrote: post #43

jjeaff wrote: post #3

Brilliant. Let unpaid volunteers fix and update the documentation for your proprietary systems so you don't have to pay someone to do it. Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?

As someone who codes offline a lot, I really appreciate when I can just clone a repo to have a full copy of the documentation.

Do You do it for productivity reasons or you happen to be offline because of some other conditions?

Re: AWS documentation is now open source and on GitHub

#70

Post by kaycebasques » Wed, Mar 14, 2018, 9:01 AM UTC

jjeaff wrote: post #3

Brilliant. Let unpaid volunteers fix and update the documentation for your proprietary systems so you don't have to pay someone to do it. Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?

As a technical writer working on an open-source docs project for another big-tech company, I can safely say that you’re overestimating the size of external contributions. People rarely want to work on docs, especially if they know that someone else is getting paid to do it.