Live data from Hacker News

AWS documentation is now open source and on GitHub

aws.amazon.com

91–100 of 102 posts

Re: AWS documentation is now open source and on GitHub

#91

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…

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

Re: AWS documentation is now open source and on GitHub

#93

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.

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?

rest (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.

Re: AWS documentation is now open source and on GitHub

#94
post #61

Earlier quoted context omitted.

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

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

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

Re: AWS documentation is now open source and on GitHub

#95
post #87
post #31

Earlier quoted context omitted.

On the one hand, I agree with you. On the other; GOD I hope it works because their documentation is loathsome sometimes.

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

They're not too bad, but then again MS has lowered my standards so much it's hard to keep perspective.

Re: AWS documentation is now open source and on GitHub

#96
post #23
post #17

Earlier quoted context omitted.

I’ve submitted bug reports about proprietary products because I want them to get better. How is this different? Or is that exploitative too?

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

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

Re: AWS documentation is now open source and on GitHub

#97
post #61

Earlier quoted context omitted.

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

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

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

Re: AWS documentation is now open source and on GitHub

#98

Earlier quoted context omitted.

YC does two things that aren't directly making money but are definitely helping their portfolio companies: 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…

Nothing is free. If you aren't paying, you're the product.

Actually, quite a lot is free. I have a free tier in my saas product. I don't monetize it in any way. I simply use it as a gateway to paying customers. I think there is probably a great deal of this going on.

Re: AWS documentation is now open source and on GitHub

#99
post #97

Earlier quoted context omitted.

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

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

Then you should shop elsewhere and accept the cost.

Re: AWS documentation is now open source and on GitHub

#100

Earlier quoted context omitted.

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

Spending time to help improve Amazon's documentation helps more than just Amazon, doesn't it?

It helps Amazon and people who pay Amazon. (basically, Amazon)
Post reply on HN