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…
AWS documentation is now open source and on GitHub
91–100 of 102 posts
Re: AWS documentation is now open source and on GitHub
#92Re: AWS documentation is now open source and on GitHub
#93It'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?
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
#94Earlier 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.
Re: AWS documentation is now open source and on GitHub
#95Earlier 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.
Re: AWS documentation is now open source and on GitHub
#96Earlier 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.
Re: AWS documentation is now open source and on GitHub
#97Earlier 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?
Re: AWS documentation is now open source and on GitHub
#98Earlier 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.
Re: AWS documentation is now open source and on GitHub
#99Earlier 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?
Re: AWS documentation is now open source and on GitHub
#100Earlier 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?