AWS documentation is now open source and on GitHub
aws.amazon.com
aws.amazon.com
Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here?
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.
I will happily take docs, such as rust's docs or NaCl's docs, which don't ever mention the possible of md5summing a password, to docs where there are hundreds of comments recommending exactly that terrible practice.
There are a practically infinite number of ways to do things wrong, and very few ways to do things right. Documenting the right way by exhaustively demonstrating the wrong ways is a fool's errand.
But more to the point, I will happily take no docs at all to docs that are more wrong than right.
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.
At worst, it was a mix of old advice, bad advice, dangerous code snippets, and people treating it like Stack Overflow.
Usually the first N posts were some really shitty solutions and someone would have to scroll way down to see a reply that calls them out and offers a good solution. But someone browsing the docs are most likely to use the first solution that seems good enough, particularly beginners.
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.
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.
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.
Sometimes it's nice to just make things better.
But if I spend a bunch of time fixing AWS docs, it's not like I have any need to fork it and use 8t as documentation for my own AWS-like service.
Intro-level documentation changes are the most common pull requests I get on any of my projects. And the people making them are not the ones being helped by intro-level docs.
It's a clear case of experts helping beginners.
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.
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.
1) Special ad positions with front-page placement (currently #22 is "Willing (YC S15) Is Hiring a UI / UX Designer" https://willing.com/designer , a privileged post that can't be voted or commented on)
2) The moderators can and sometimes do intervene by removing certain comments that are critical of YC companies.
Comments make the forum more interesting to the community, which increases eyeballs and makes the front page spots more valuable. And shaping the discourse helps with damage control when necessary.
YC doesn't make money directly from the forum. But neither does AWS from their docs.
If you have a problem with a company making money directly from your content, why doesn't it bother you if they are gaining something else off you like influence? Do you think HN confers zero value to YC?
Engineers generally have a natural tendancy to fix things, and documentaitons are worth fixing. And it also helps their future work.
I think that's a much better goal than helping Amazon make money.
I'm a freelancer and when I am between client projects I try to just code without the internet for a few hours first thing in the day.
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.
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.
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.
Another is to consider this as Amazon giving the users a standard, simple way of fixing the documentation issues they inevitably run into.
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
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?