12 ms·
AWS documentation is now open source and on GitHub
- shady-lady 9y agoI 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 9y agoI wrote it -- do I need to make a fix??
- shady-lady 9y agowell, 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.
- jjeaff 9y agoBrilliant. 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?
- pcurve 9y agoIt's a great resume padder.
- pvsnp 9y agoIf it's not a huge change I'd rather suggest a fix while I'm in middle of something so that I don't have to update internal company documentation + code comments for special cases. Comes with caveats of course, like I'm not going to spend a lot of time waiting to merge the PR for Amazon's docs. But given how many people use it, it's sort of for greater good anyway.
- est 9y agoI think php.net's documentation with comments was better.
- eropple 9y agoThat documentation devolved over time into a tire fire of bad and dangerous advice.
- est 9y agowhich 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.
- TheDong 9y agoI disagree. 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.
- jjeaff 9y agoI would wager that you won't find an obviously bad security practice like md5() the password in the PHP documentation comments that isn't voted way down.
- eropple 9y agoYou 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.
- edpichler 9y agoI think it’s because some people just like to help things get better. And there is no problem about this.
- quadrature 9y agoWell as a user of Amazon you have a vested interest in the documentation being correct. It is what other members of your team and organization will be referring to. Having it on GitHub will also add additional context around changes in the form of PRs, Issues and the commit history.
- kartan 9y ago> Well as a user of Amazon you have a vested interest in the documentation being correct. 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.
- ShorsHammer 9y agoIf there was an aisle full of cardboard boxes blocking you from buying a product would you leave the store or take 5 seconds to move the boxes?
- dystq 9y agoWhat if 90% of Walmart aisles were consistently blocked by aisle-blocking cardboard boxes and Walmart decides the solution is to use social engineering to encourage more customers more often to take 5 seconds to move the boxes?
- ShorsHammer 9y agoThen you should shop elsewhere and accept the cost.
- SkyPuncher 9y agoI tend to feel the same way, but would happily throw in a couple of changes (which when you multiply by thousands of people, makes a lot). 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.
- oh-kumudo 9y agoIf it is one/two lines, why not.
- osteele 9y agoI’ve submitted bug reports about proprietary products because I want them to get better. How is this different? Or is that exploitative too?
- jjeaff 9y agoBug reports are a little different than the product itself. I guess my take is that yes, if you needed it fixed because you are using it, then it makes sense. 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.
- osteele 9y agoDocumenting something you've just figured out, for other's benefit if not your own, is a pay-it-forward (or golden rule, or reciprocal altruism) approach: behave such that if other people behaved likewise, you would benefit.
- dcosson 9y agoWhy is it any different than documenting open-source code for free, or answering a stack overflow question?
- always_good 9y agoYeah, 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 9y agoWith 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 9y agoImproving 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.
- mgkimsal 9y agopartially because you're presumably paying for the amazon service, but not necessarily with an open source project. one of the ways some people 'pay' for using an OS project is by helping in forums/docs/etc. presumably, the money you're paying for amazon services is/should be going in to their documentation. 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.
- tdb7893 9y agoI've noticed documentation bugs and submitted them to amazon before they open sourced this. Overall for documentation I've just fixed things as I find them and I've never seen it as much of a burden and it helps the community
- dlhavema 9y agoSame here. This just kinda standardizes the process in a way that makes edits super clear...
- always_good 9y agoJust think of all the uncompensated value you've given Y Combinator every time you've left a quality comment on their forum.
- icantdrive55 9y agoI'm o.k. with it here. It might even ruin the site if money was even offered to Moderstors. That said, I don't like when people/companies exploit human nature. Most of us want to help, learn, or just communicate. My biggest gripe is when a dude is filthy rich, and it's usually a man; and they just cheap everything out. The thinking is awalys, I built it, and I'm not breaking any law. It goes double for companies who set up shop in the closest hole to save few bucks. Yes--no man made laws were broken, but morals/ethics--morals I was brought up with were broken. It get's worse every decade, and very few call these guys out. Instead, they are put on pedastools? Actually, clever hypocrites have seized on to the problem, but even at over a year (418 days), nothing is changing. I don't need to mention the charlatan. I see the selfishness everywhere. It's just greed wrapped up in different, clever packaging. And I know we're not suspose to comment on how the upper class (God--I don't know why they are called upper class.) think. All I know is they have abused their position, a position of influence because of their wealth, to a disgusting level. I am forced to live among them. I give them half smiles. I'm polite. I have zero respect for them though. And when they do decide to give a bit back; they can't just give. They need to micromanage the "gift", or put their name on it. They just can't give. And I'm not just picking on tech/manufacturers. I see it everywhere. I usually just have to follow the money to find the rat. I'm not in a good mood? Everytime I tell my version of what I'm seeing, I feel the need to make excuses. Why? Because I know their will be the usual backlash, and justification--usually by the unpaid/underpaid followers of these guys.
- samschooler 9y agoThen again, Y Combinator makes no direct money off HN. AWS’ docs, if they are quality directly impacts their profit because more people can use their services more easily.
- TAForObvReasons 9y ago
- Zelphyr 9y agoOn the one hand, I agree with you. On the other; GOD I hope it works because their documentation is loathsome sometimes.
- Zelphyr 9y agoLiterally just ran into this. One AWS doc example says to use "update" whereas another doc says to use "updateItem". Which one works? No way to tell without trying. Their documentation is literally costing me productivity at this point.
- ShorsHammer 9y agoThey're not too bad, but then again MS has lowered my standards so much it's hard to keep perspective.
- helthanatos 9y agoI don't want to make the same mistake when doing something. It's more of a service to other people than to Amazon (People probably aren't going to choose a different service based on documentation). It also helps to have different viewpoints from levels of experience to help with wording and such.
- orsenthil 9y agoOn the other side, what if Amazon gets sued based on something written by a volunteer contributor?
- joevandyk 9y agoWhy do people put in countless hours of free labor for Jimmy Wales?
- ReverseCold 9y agoBecause 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.
- joevandyk 9y agoSpending time to help improve Amazon's documentation helps more than just Amazon, doesn't it?
- ReverseCold 9y agoIt helps Amazon and people who pay Amazon. (basically, Amazon)
- ioddly 9y agoAs someone who codes offline a lot, I really appreciate when I can just clone a repo to have a full copy of the documentation.
- jve 9y agoDo You do it for productivity reasons or you happen to be offline because of some other conditions?
- ioddly 9y agoMostly column A, a little column B as well (sometimes I travel). 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.
- hamzilla 9y agoUltimately I make docs for myself so it's easier next time. And i forget ... everything.
- kaycebasques 9y agoAs a technical writer working on an open-source docs project for another big-tech company, I can safely say that you’re overestimating the size of external contributions. People rarely want to work on docs, especially if they know that someone else is getting paid to do it.
- arrow64 9y agoKeep in mind that this also makes it easier for any Amazon employee to improve documentation. That's 1,000s of developers who are equally confused about AWS APIs and are incentivized to make it better.
- taspeotis 9y agoMicrosoft 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.
- jehlakj 9y agoIssues. Make their outdated docs known. I think that’s the main benefit.
- maltalex 9y agoThat’s one way of looking at it. Another is to consider this as Amazon giving the users a standard, simple way of fixing the documentation issues they inevitably run into.
- swaroop 9y agoBecause their "OPW strategy" is designed to incentivize people to contribute - https://youtu.be/I3LrtjsE6eg?t=16m17s https://youtu.be/I3LrtjsE6eg?t=16m17s
- kartan 9y ago> 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/using-volunteers-and-interns-is-it-legal/ 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 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.
- gnud 9y agoWhile that's an interesting point, it's not as simple as it being 'illegal' either. 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.
- INTPenis 9y agoHeh that's a very cynical view and it speaks to me. But my first thought was that this will make me choose AWS over alternatives because I've found the docs for GCP very confusing and sometimes outdated. 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.
- cup-of-tea 9y ago> Can someone explain to me why people will inevitably put in countless hours of free labor for Amazon here? 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".
- gaius 9y agoBut how is that different to answering questions on SO? 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
- vinniejames 9y agoBecause the existing docs are pretty terrible, I'd be thrilled to help update them to make my life easier
- pvsnp 9y agoI 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.
- Terretta 9y agoAzure 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/
- voidhorse 9y agoUh 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.
- jawns 9y agoOn 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.
- whoisjuan 9y agoHmmm. Well then any content is open to exploitation, regardeless if it's open source or not. I can basically copy and paste your comment on my own website and change its content...No fork would ever have as much authority as the original repo since that's the one linked and referenced everywhere. This is exactly the problem that Google solved when they created the PageRank algorithm.
- TheDong 9y ago> 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 9y ago
- ivan_ah 9y agoIt'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 9y agoJust 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 9y agoReST 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-markdown-for-technical-documentation/ https://eli.thegreenplace.net/2017/restructuredtext-vs-markd... http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ 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/docs/conf.py#L447 https://github.com/ivanistheone/ricecooker/blob/docs/improve...
- accordionclown 9y agorest (restructured text) has been used for python documentation for a very long time. so -- especially for that particular usage -- it's much more functional and clearly documented and consistent and free of edge-cases than (the far-too-numerous flavors of) markdown. 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.
- Rapzid 9y agoThis 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 9y agoYou 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 9y agoIt 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/".”
- crb002 9y agoFinally. Been asking for this for years.
- d_burfoot 9y agoGah, 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/doc-source/cli-dynamodb.md 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.
- vasco 9y agoWhile 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.
- foreigner 9y agoNow if only they would open-source the AWS Console...
- hallzi 9y agoCool! How does aws translate their docs?