Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?
In general, I'm happy supporting a company that pushes the bounds rather than fretting over every little detail. If something doesn't work exactly as documented, I probably found a rather unique case. I'd rather struggle with the problem for an hour and suggest a fix, than have X, Y, or Z company pay someone to spend countless hours finding every possible edge case.
----
On top of that, there is a hugely beneficial conversation that often arises from the opening of issues. I've found that one of the best ways to engage in a meaningful discussion with a company is to open an issue on one of their code repos. Engineers are often more straight to the point than "marketing" or "business" types.
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.
Having it on GitHub will also add additional context around changes in the form of PRs, Issues and the commit history.
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.
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.
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.
Sometimes it's nice to just make things better.
also... with an OS project, I can actually get the code and see how it runs, test patches, etc. I can't actually do that with their services, and any docs I might contribute would be guesstimates as to how things actually work, vs how it actually does work (and what's intended), which would/should come from the company that actually owns the code in question.
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.
I've told vendors of documentation bugs - and they've even listened. I wasn't paid by the vendor, I was paid by my employer. Who has a business relationship with the vendor. I sort of doubt this is illegal.
I wish I knew. Reminds me of Google Map Maker, aka "Work for Google producing proprietary mapping data that even you can't get back for free".
The payoff in this case is probably getting your name into the official docs and leveraging that reputation as an AWS guru into pay/promotions later
Another is to consider this as Amazon giving the users a standard, simple way of fixing the documentation issues they inevitably run into.
But in the case of documentation, by the time I figured things out and see that the documentation is wrong, I no longer need the docs and I know what to do.
I think that's a much better goal than helping Amazon make money.
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.
For code samples do they do something similar to Mozilla?
Mozilla MDN:
“Code samples and snippets
Code samples added on or after August 20, 2010 are in the public domain (CC0). No licensing notice is necessary, but if you need one, you can use: "Any copyright is dedicated to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/".”
If this collaborative-documentation initiative were launched as an Amazon-hosted wiki, editors or mods could shut me down. But since it's open source and under a Creative Commons license, Amazon has essentially no control over how much I vandalize the content.
Fortunately for AWS, I'm not really interested in vandalizing the content or misleading people. But the fact that someone can create a knock-off site riddled with errors, and Amazon can't claim copyright infringement if the site plays by the Creative Commons rules, is concerning, isn't it?
Edit: I know, I know. It's already possible to make unauthorized copy-pasta sites. But at least Amazon would have the ability to threaten the site's owner or hosting provider with copyright infringement claims. That option disappears when you release your official documentation under a Creative Commons license.
You misunderstand trademark law.
Trademark law is meant to prevent confusion, and would kick in here.
Nothing is different with respect to creating a confusing fork; before they wouldn't claim copyright infringement before either, but trademark infringement.
Something like that change should have a message explaining why that change is proposed.
Unfortunate that the blogpost itself can't be forked :p
imagine down the line somebody submitting changes & the message isn't the reason why those changes are there[0] but instead a copy paste of the changes[1]
[0] e.g. "remove fuzzy language"/"update intro to more accurately reflect addition of new services"
[1] not denying that sometimes this makes more sense.
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.
The main advantage for ReST is that it is well defined and consistent. It's a bit heavier than .md, but I think it will pay off for large projects.
Here are some articles about it: https://eli.thegreenplace.net/2017/restructuredtext-vs-markd... http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-f...
I've written docs for personal projects in markdown, but now that I work on larger collaborative projects I feel like ReST is the way to go.
PS: If you're using Sphinx, you can actually support both .md and .rst in the same project, and slowly transition from one to the other, see https://github.com/ivanistheone/ricecooker/blob/docs/improve...
on the negative side, there aren't many quality authoring-tools for rest.
markdown has a very high profile. but it's questionable whether it deserves it. (i wouldn't say that it doesn't. but i wouldn't say that it does, either.)
another option you could look at is asciidoc. it isn't clearly better or worse than those other two systems, but it is different, and you might end up liking it better. (or you might not.)
light-markup systems are much like static blog systems. there's a lot of them, but it's hard to decide among them, and many people end up inventing their own variant that serves their own individual use-cases.
1. They can add their contributions to their resumes. 2. They use the software and more than likely reference the docs, and so are already stakeholders that desire the content to be correct and so will happily fix it given the chance so that they can save themselves headaches in the future. 3. The general concept of 'open source' is very enticing and is almost always has a positive connotation, so very few people will see that this is a clever way to cut costs and net free labor and not really the virtuous public gesture of transparency and good will a lot will perceive it to be.
This would be different if, like actual open source software others could pull the thing and conceivably make a better version of it and compete, but since this is necessarily bound to a product that's not going anywhere outside the organization, it's de facto always going to be free labor for amazon and never going to promote potential forking out of modified versions of the project, further securing the companies foothold in the market as well--after all, if you no longer have to pay folks for all the extra bits like documentation, support, and maintenance of internal libraries, you can have nothing but a horde of devs working on the user-facing product, and ensure all of your money goes toward nothing other than squashing the competition. Sure you could argue it's still technically possible for someone's fork to gain bigger traction than the official amazon repo, but cmon now, the project is so massive and is so bound to the company that such a scenario is highly unlikely. On the plus side, open sourcing is a boon for archivists were the main content to ever disappear (unlikely).
I realize this sounds a little bleak, and I'm sure amazon also has good intentions with this move, but I can't help but see the potential for future markets where a lot of free labor is snagged under the banner of 'open source' simply because people are shortsightedly seeking resume boosts and not realizing that contributing labor freely will more than likely hurt the job market in the long run.
Not saying you shouldn't contribute to open source, nor is the idea of open source a bad one, but I think the lines get a bit blurred when it comes to open source projects owned by private (massive, in this case) corporations who are then gaining from the work of outsiders without needing to compensate them. Sure, helping out looks good on your resume, just as unpaid internships do--but at some point we need to take a look at these practices that can be, whether intentionally or not, ways of sidestepping the proper dispensation of wages and compensation for labor.
They may still need to pay somebody to green light merges, but that's a lot less costly, I imagine, than paying a team of writing professionals.
why does going to one university vs another carry more weight with some people?
