Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

“This is the worst documentation I have ever seen in my life”

github.com

Post reply on HN
Print view View original

41–50 of 112 posts

Re: “This is the worst documentation I have ever seen in my life”

#41

Post by Raphmedia »

bluntfang wrote: post #30

I feel like linking directly to issue pages incites brigading. This HN post seems like a direct attack on the maintainers (not the actual issue). Look at the new comments posted since this link hit frontpage. Not helpful, and in fact HARMFUL to open source at large. This is irresponsible.

I would agree if this linked to a small project or someone's personal open-source project.

However, this is the repository to the public documentation of Amazon's API.

This is not the source code to a website somewhere. This is the actual documentation. You ask Amazon for the documentation and they link you to that repository.

This is a company with a revenue of $96.1 billion that relies on sellers to fill its marketplace. You would expect some level of quality.

We had an issue at work with their Seller API. We ended up having to email and call their support daily in order for them to switch an invisible flag on our account. After a month and a half of phone calls, they eventually fixed it.

This is the kind of support you receive from Amazon when you are a seller.

Re: “This is the worst documentation I have ever seen in my life”

#42

Post by MattGaiser »

m45t3r wrote: post #18
forsaken wrote: post #13

Earlier quoted context omitted.

Sphinx supports this for Python: https://www.sphinx-doc.org/en/master/usage/extensions/doctes...

This is actually something from Python's stdlib: https://docs.python.org/3/library/doctest.html Really underrated.

My job is mostly Python. Did not know this existed.

Re: “This is the worst documentation I have ever seen in my life”

#43

Post by h2odragon »

llimllib wrote: post #3

~13 years ago (!) I worked with the Amazon Seller API and left this comment in my own source code: // the XML returned from this request is *mind-bogglingly* bad. Terrifyingly bad. // a completed batch looks like this: // batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 // and an incomplete batch like: // batchid=363778361 status=In Progress /…

the text based format in that implies lovely horrors. now all it needs is sometimes quoted items after "key=" (using and requiring different quotes, depending on which system you're speaking to) and at least 3 sources of "universal event ID" counter... just one "batchid" is too simple.

Re: “This is the worst documentation I have ever seen in my life”

#44

Post by merb »

breck wrote: post #22
hpoe wrote: post #5

Just an FYI. This is about Amazon's MWS API, which is Merchant Web Services, used to interact with the Amazon part of Amazon not the AWS side of Amazon. Also having working on an OSS Ruby library for it, and having to had work with it quite a bit, I can confirm. The MWS APIs leave a lot to be desired of, but they are an absolute gem compared to the Ebay APIs. My take on the problem is that these APIs were developed i…

I think you've explained the situation quite well. I got my career started helping a lot of big companies transition from SOAP/WSDL/XML tech to JSON APIs in the late 2000's (writing API servers and client libraries in PHP, Ruby, Python, and then Node.js) and so thought about these technologies day in and day out for many, many years. I think we are still missing a dead simpler way to do it all—a very basic Tree/Grid…

> Higher level types would be added onto that, but at the low level it's all about just keeping your data as simple and clean as possible.

and at the end we would call it rpc and gave the binary protocol a better name, like protobuf or cap'n'proto?

Re: “This is the worst documentation I have ever seen in my life”

#45

Post by VWWHFSfQ »

m1gu3l wrote: post #15
hmaxwell wrote: post #7

I won't touch any of amazon's products with a 10ft pole because of the way they treat their warehouse workers. Making their warehouse employees pee in bottles to make their metrics or risk being fired, that's just on a whole new level of extracting every joule of work out of a human being.

fair but wildly off-topic.

no no the topic of this post is "amazon bad"

Re: “This is the worst documentation I have ever seen in my life”

#46

Post by [deleted] »

SeeDave wrote: post #31
llimllib wrote: post #3

~13 years ago (!) I worked with the Amazon Seller API and left this comment in my own source code: // the XML returned from this request is *mind-bogglingly* bad. Terrifyingly bad. // a completed batch looks like this: // batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 // and an incomplete batch like: // batchid=363778361 status=In Progress /…

batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 Philosophically speaking, is this any different than 'syntactic salt' for a 'Batch' JSON object? ;)

[deleted]

Re: “This is the worst documentation I have ever seen in my life”

#47

Post by johnc1231 »

MattGaiser wrote: post #2

We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.

We do this for our project (https://hail.is) and it's a game changer. Saves so much time and so many bug reports.

Re: “This is the worst documentation I have ever seen in my life”

#48

Post by raverbashing »

hpoe wrote: post #5

Just an FYI. This is about Amazon's MWS API, which is Merchant Web Services, used to interact with the Amazon part of Amazon not the AWS side of Amazon. Also having working on an OSS Ruby library for it, and having to had work with it quite a bit, I can confirm. The MWS APIs leave a lot to be desired of, but they are an absolute gem compared to the Ebay APIs. My take on the problem is that these APIs were developed i…

Don't worry, the docs and APIs/libraries for AWS are just as bad

Boto3 is eye-watering bad. Boto2 was written by someone with some knowledge of Python and usability. Boto3 is just "automatically generated" from their API

It is not good. It is bad. The structure makes no sense. The API can be described as "the minimum that works".

Re: “This is the worst documentation I have ever seen in my life”

#49

Post by FeepingCreature »

MattGaiser wrote: post #2

We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.

If you write a unittest in D underneath a function, it will automatically be included in the generated docs as an example. This is how all the examples in the standard library documentation are created, so you know for a fact that those work.
Post reply on HN