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?

Azure says come in in, the water’s fine.

https://github.com/MicrosoftDocs/azure-docs

https://docs.microsoft.com/en-us/contribute/

I for one, welcome this change.. assuming I can grep for what I'm looking for in the repos. Or maybe Dash will integrate the docs so I don't have to browse around on metered LTE networks.

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?

It looks like at least some of the guides are licensed Creative Commons BY-SA.

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/".”

On a lark, I just forked the repo for the AWS CLI user guide and added some commits that introduced subtle and not-so-subtle errors. Let's hope my fork never shows up in search results. Otherwise, people are going to be making curl requests to r/tacobell to download the AWS CLI Bundled Installer.

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.

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

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.

It's interesting that they mix markdown and restructured text. ReST is clearly the superior formatting language, but markdown is so much easier to pick up and use.

Uh oh, looks like my tech writing career is under threat (so of course I'm posting with a bit of bias here). A wise move on amazon's part though, offload your work on to users who will improve the docs for a couple of reasons:

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.

Cool! How does aws translate their docs?

Finally. Been asking for this for years.

Now if only they would open-source the AWS Console...

I find interesting the assumption every comments make that people are "dumb enough to work for free for Amazon if it's openly accessible". To give the possibility to everyone for proposing changes to their documentation doesn't mean EVERYONE will propose changes. It simply means people who have interest in doing so will be able to do it more easily. We can see this like a reduction of the cost of communication for everyone who have interests at a better Amazon's documentation. To me, it looks like common sense : you won't give money to someone for fixing a comma, because it's not hard and therefore it's not labor. The power of internet is that the work can be split among so many people that the "work" isn't "work" anymore. If it take everyone participating only 5 minutes a day to improve the documentation, then I cannot see how you would remunerate people with money. People can however still point to their github accounts to prove they contributed, and they "earn" reputation instead of money (ala StackOverflow).

I'm curious. What makes contribution to this docs so special that adding it to the resume has been mentioned a few times in this thread? I mean, is it not just another repo you have contributed to in your github profile?