
AWS documentation is now open source and on GitHub - sassyboy
https://aws.amazon.com/blogs/aws/aws-documentation-is-now-open-source-and-on-github/
======
jjeaff
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?

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

~~~
always_good
Yeah, it's kind of like wondering why someone would make an open source
project better when the person that owns the repo gets all the credit. Or all
the competitors they might be inadvertently helping out by improving the
project.

Sometimes it's nice to just make things better.

~~~
jjeaff
With an open source project, I can fork and use the code for myself and
contribute back to the project.

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.

~~~
always_good
Improving an open source project's docs aren't likely to help you, either.

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.

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

[https://github.com/MicrosoftDocs/azure-
docs](https://github.com/MicrosoftDocs/azure-docs)

[https://docs.microsoft.com/en-us/contribute/](https://docs.microsoft.com/en-
us/contribute/)

~~~
cheeze
I know it's been a while, but I still cant get over the azure outage that
lasted almost a full day in 2012.

~~~
nhumrich
Thats a very long time ago in cloud computing years.

------
pvsnp
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.

------
Rapzid
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?

~~~
always_good
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.

------
lloydde
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/".”](http://creativecommons.org/publicdomain/zero/1.0/".”)

------
jawns
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.

~~~
TheDong
> 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.

~~~
jawns
Nominative fair use should cover that. Otherwise, no one could write an
"Unofficial Guide to ..." any technology or service with a trademarked name.

------
shady-lady
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

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

~~~
shady-lady
well, it depends on what type of comments you guys find acceptable & would
want to see when you're deciding whether to merge the changes in.

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.

------
d_burfoot
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...](https://github.com/awsdocs/aws-cli-user-
guide/blob/master/doc-source/cli-dynamodb.md)

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.

~~~
vasco
While for docs which are very close to code, you're right, good documentation
has a lot of things at much higher level than code, and a lot of times
teaching people how to do things unrelated to the actual implementation, ie
"how to expand a linux file system after you increased an EBS volume". Your
comments are a bit reductionist.

------
ivan_ah
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.

~~~
johnhenry
Just curious, I've never actually heard of "ReST" as a format before now... I
wonder if you might be able to explain what makes it superior to markdown?

~~~
ivan_ah
ReST is really big in the Python ecosystem, thanks to Sphinx (docs generator),
and the read-the-docs website.

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...](https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-
technical-documentation/) [http://ericholscher.com/blog/2016/mar/15/dont-use-
markdown-f...](http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-
technical-docs/)

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...](https://github.com/ivanistheone/ricecooker/blob/docs/improve/docs/conf.py#L447)

------
voidhorse
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.

~~~
rapfaria
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?

~~~
voidhorse
It may just be another repo at the end of the day. Point is, contributions to
open source are sometimes considered when selecting job candidates, so it
remains an incentive for folks that may be strong enough for it to nudge them
to do work for Amazon. I.e. even though it's technically free labor, I
_potentially_ benefit in some way thus I'm content. The problem is potential
edge in future job searches is a far more ephemeral form of compensation for
your time, is not concretely measurable, and is not actually provided by the
company the labor was completed for. In the end the company ends up with a
tangible product which they can use to compete in a market and the open source
contributor ends up with, at best, a potential benefit should she ever need to
apply to some job that will actually pay her for her work in the future.

------
hallzi
Cool! How does aws translate their docs?

------
crb002
Finally. Been asking for this for years.

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

