Earlier quoted context omitted.
Personally, I'm surprised that's a controversial statement.
Its not on this forum. Its so common as to be a cliche.
It's eye-roll inducing at this point.
AWS documentation is now open source and on GitHub
81–90 of 102 posts
Re: AWS documentation is now open source and on GitHub
#82I 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
I wrote it -- do I need to make a fix??
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.
Re: AWS documentation is now open source and on GitHub
#83Earlier quoted context omitted.
Then 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.
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…
..and collect your personal data, non-directly-identifiable data or otherwise, from both of which they may earn some money (if i understand the privacy policy correctly.. am no lawyer, though)
Re: AWS documentation is now open source and on GitHub
#84It'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 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... 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...
Re: AWS documentation is now open source and on GitHub
#85Brilliant. 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?
Because the existing docs are pretty terrible, I'd be thrilled to help update them to make my life easier
Re: AWS documentation is now open source and on GitHub
#86On 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.…
> 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. Not…
Nominative fair use should cover that. Otherwise, no one could write an "Unofficial Guide to ..." any technology or service with a trademarked name.
Re: AWS documentation is now open source and on GitHub
#87Brilliant. 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?
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
#88Now if only they would open-source the AWS Console...
Re: AWS documentation is now open source and on GitHub
#89Cool! How does aws translate their docs?
Re: AWS documentation is now open source and on GitHub
#90Earlier quoted context omitted.
As someone who codes offline a lot, I really appreciate when I can just clone a repo to have a full copy of the documentation.
Do You do it for productivity reasons or you happen to be offline because of some other conditions?
Mostly 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.