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

71–80 of 112 posts

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

#71

Post by typenil »

glaucon wrote: post #56
raverbashing wrote: post #48

Earlier quoted context omitted.

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

I'm not here to defend AWS but I'm a bit puzzled by your comment about the Boto3 doco. Here's some sample usage for instance which clearly is something more than "automatically generated" https://boto3.amazonaws.com/v1/documentation/api/latest/guid... .

I believe they meant that the API bindings themselves are autogenerated - which I think is pretty likely given how baffling and un-pythonic some of decisions in boto3 are.

You're right that much of the documentation clearly isn't auto-generated. Of the many Amazon APIs and tools I've worked with, boto3 among the better of them in terms of documentation.

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

#72

Post by gfaure »

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 /…

I note with horror that "activated" is misspelt in "itemsnotacivated" but spelt correctly in "activateditems".

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

#73

Post by kingaillas »

bfieidhbrjr wrote: post #21
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 /…

reminds me of a description of MSFT's first XML-based office file formats (not sure if its true or was a joke) but it went something like wky4b5tlwybkjbb2...

I kind of remember a massive CDATA blob... but my memory must be playing tricks on me: Wikipedia shows some sample markup of the pre-2007 Microsoft Office (https://en.wikipedia.org/wiki/Microsoft_Office_XML_formats) and it doesn't look bad at all.

And it seems after 2007 they switched to an ECMA standard.

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

#74

Post by sonny3690 »

I know it doesn't solve all the aspects of how broken this documentation is: but here's a pull request that somewhat tries to address it.

The Pull Request:

https://github.com/amzn/selling-partner-api-docs/pull/209

The Deployed Docs:

https://docs.contour.so/amzn/selling-partner-api-docs

Lots of bugs still to fix but hopefully it's helpful to anyone. Super open to any feedback!

---- Edit: To make it clear, the docs are built on a web app I built while on break from school. Sorry if that wasn't clear before!

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

#75

Post by nl »

nograpes wrote: post #52
hprotagonist wrote: post #14

can i introduce you to my friend openCV? :/

I thought I was the only one! When I look around at the code examples using openCV it is clear that nobody knows how to use it. God help you trying to get your GPU working on Python.

Matplotlib...

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

#78

Post by bredren »

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 agree that this issue was likely not helpful except to shame Amazon. Sometimes publicity of things like this gets change that calm requests will not.

That said, I wrote documentation professionally for a few years in my career, and recently re-worked much of CRACO's documentation, and there is very little love for docs.

Docs are hard to do well and completely and if the API is as bad as described, you can only shine up a turd so much in explaining how something works.

Sometimes writing documentation is the only way someone realizes that the software is broken or not actually useful as implemented.

In most situations, a product manager is looking out for this in advance, but when the product is purely an API you have less product-type people who can provide useful management.

Obviously it is not a revenue problem at Amazon. Perhaps this is anger at Amazon's astonishing success redirected to areas of Amazon that have failed to realize the resources to make quality products.

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

#79

Post by Smaug123 »

qayxc wrote: post #23
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.

That's definitely something that's still missing in technical documentation. The tooling still isn't there yet, and that's sad. Every change in API or behaviour should be automatically blocked by CI tooling in release builds if its documentation is missing or outdated. But alas, even in 2020 technical documentation is still just an afterthought for most companies - even big ones.

Internally to $WORK I've got a documentation system consisting of interactive F# notebooks, put together automatically from marked-up F# code (so you get type-checking while you write them) with output assertions checked in the CI pipeline for the corresponding library (and before a pipeline pushes out the latest version of the documentation). Hoping to open-source the system if I ever get time; I think Mathematica's documentation system is absolutely first-class, and I want that in any language that supports notebook-style interfaces!

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

#80

Post by bredren »

sequoia wrote: post #50

Seems that API documentation (in this case) is not terribly important to the bottom line :) (So why should the bother fixing it?)

This was the case on the dev side of iTunes Connect and the App Store for longer than anyone at Apple would like to admit.

It was clear for a long time that developers were not considered customers, or if they were, they were far less important ones.

Post reply on HN