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

Re: AWS documentation is now open source and on GitHub

#51

Post by always_good » Wed, Mar 14, 2018, 4:26 AM UTC

Rapzid wrote: post #38

This is.. Odd. AWS is notoriously a black box. Their services aren't open source and on github; who would have the insider view necessary to work on the docs outside of their own employees? Is this easier than having an edit suggestion feature? Will PR's cause clashes with their technical writers?

You don't need system insight to improve docs. On one end of the spectrum, docs just need people to improve the language like typos, grammar, and sentence flow.

Also, docs map out the black box but end-users use the black box. They are in a position to find disparities between what the docs say and what the black box does. Like noticing the example response doesn't match the actual response.

Or that if you provide a stream to the API, you must provide a content length, yet this relationship is only marked as optional in the docs.

Maybe an engineer would have to double-check the code to verify the behavior, and that's great.

Re: AWS documentation is now open source and on GitHub

#52

Post by ReverseCold » Wed, Mar 14, 2018, 4:29 AM UTC

joevandyk wrote: post #39

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?

Why do people put in countless hours of free labor for Jimmy Wales?

Because that labor isn't for Jimmy Wales, it's to further the education of the entire world (Wikipedia is free).

I think that's a much better goal than helping Amazon make money.

Re: AWS documentation is now open source and on GitHub

#53

Post by taspeotis » Wed, Mar 14, 2018, 4:34 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?

Microsoft do this and seems to make it a cooperative effort. They do have people working on it full time and would be within their rights to NOT accept contributions from the community. But they do, and those contributions are vetted by the full time staff.

As long as this is in the spirit of collaboration and not a "source code dump" that a lot of commercially-backed projects do to earn an "open source" moniker ... I'm fine with it.

Re: AWS documentation is now open source and on GitHub

#54

Post by jehlakj » Wed, Mar 14, 2018, 4:42 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?

Issues. Make their outdated docs known. I think that’s the main benefit.

Re: AWS documentation is now open source and on GitHub

#55

Post by eropple » Wed, Mar 14, 2018, 4:42 AM UTC

est wrote: post #30

eropple wrote: post #27

Earlier quoted context omitted.

That documentation devolved over time into a tire fire of bad and dangerous advice.

which is still better than no advice at all. It's good to know there are bad practices out there, and the doc team should update the doc and show how to avoid bad practice.

You could still find new, fresh advice about using `mysql_query` as late as like 2013 on there. I don't think it's better to have that advice than none at all.

Expecting a "doc team" for an open-source language to keep on top of what fresh hells people are doing with forever-deprecated things seems like a very big ask.

Re: AWS documentation is now open source and on GitHub

#56

Post by joevandyk » Wed, Mar 14, 2018, 4:52 AM UTC

ReverseCold wrote: post #52

joevandyk wrote: post #39

Earlier quoted context omitted.

Why do people put in countless hours of free labor for Jimmy Wales?

Because that labor isn't for Jimmy Wales, it's to further the education of the entire world (Wikipedia is free). I think that's a much better goal than helping Amazon make money.

Spending time to help improve Amazon's documentation helps more than just Amazon, doesn't it?

Re: AWS documentation is now open source and on GitHub

#57

Post by swaroop » Wed, Mar 14, 2018, 5:37 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?

Because their "OPW strategy" is designed to incentivize people to contribute - https://youtu.be/I3LrtjsE6eg?t=16m17s

Re: AWS documentation is now open source and on GitHub

#58

Post by kartan » Wed, Mar 14, 2018, 5:48 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?

> Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?

Most people is good a heart and they want to help, even when it's bad for themselves or even illegal.

"Under the federal Fair Labor Standards Act (“FLSA”) and many state and local wage and hour laws, the use of volunteers and interns is strictly regulated." https://www.forbes.com/sites/richardtuschman/2012/08/24/usin...

Amazon strategy is just another example of "if it's online it's legal". Destroying jobs in exchange of "experience", "visibility" or "a better curriculum" is regulated and for good reasons.

Do they want their software to be free? That's good. Everybody can use it and anyone can collaborate. Do they want their documentation to be reviewed and expanded by voluteers? Why not hire Technical Writers?

https://en.wikipedia.org/wiki/Technical_writer

Amazon evades paying taxes while expecting that volunteers do their job instead of employees. The world economy can't continue running like this for long.

Re: AWS documentation is now open source and on GitHub

#59

Post by kartan » Wed, Mar 14, 2018, 5:57 AM UTC

dcosson wrote: post #18

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?

Why is it any different than documenting open-source code for free, or answering a stack overflow question?

> documenting open-source code for free

Foundations that own the open-source projects are allowed to use volunteer work by law. Corporations with a for-profit interest doesn't.

> or answering a stack overflow question?

This one is more tricky. But it depends on who asks the question? It is an individual to get help on a problem? Or is it part of the ways of working of a company to avoid hiring experts? Evaluating intention it's usually hard.

Re: AWS documentation is now open source and on GitHub

#60

Post by crb002 » Wed, Mar 14, 2018, 5:59 AM UTC

Finally. Been asking for this for years.