“This is the worst documentation I have ever seen in my life” (opens in new tab)

I kid you not, I know exactly what you're talking about there. I also wrote my own regex parsers with fast-forward and rewind tokenizers, because it was so dreadful. I wouldn't normally do that.

There's also 4 (4!!!) different ways of returning errors in the MWS Feed APIs when used from Java. Given the number of entities, and the fact that they're combinatorial I had to do some of the craziest Scala code I've ever written because duplication was just too bad to handle for how critical that code was. To do it in a bulletproof way, that error handling for MWS feeds inherently has 2^4 control flows * N entities = 16N code paths at like 100-200 lines a piece if you didn't use some higher order abstractions.

That looks like putting "<Batch>" and "</Batch>" around a legacy text format and call it a day, to report that your service/API "supports XML" lol. Actually, SGML has mechanisms (shortrefs and "data tags") to parse strings like that as markup and could even infer "<Batch>" tags (but it still won't work satisfactorily with your example data).

I was kind of hoping for:

<Batch batchstate="batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17" />

:)

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

<xml> <office-proprietary-binary-blob> wky4b5tlwybkjbb2... </office-proprietary-binary-blob> </xml>

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

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.

<Batch>batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 </Batch>

Philosophically speaking, is this any different than 'syntactic salt' for a 'Batch' JSON object? ;)

Were they not using a standard XML serialization library?

Jesus christ just kick me in the balls than making me deal with that XD

This is not the MWS API. The MWS Api was indeed written more than 10 years ago but is much better than this new "REST" api.

This is Selling Partner API which was released few months back and is intended to replace MWS.

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 Notation where API requests and responses are equivalent to sending a spreadsheet back and forth (no syntax characters—no quotes, ticks, brackets, parens, etc—just spacing for the encoding). 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.

Here's a demo I made in 2014 of the idea, which I think is as relevant as ever https://www.youtube.com/watch?v=DV4Nv23bBwQ&t=4s

And another look at it: https://treenotation.org/#apis

Agree with what you have said about the MWS API, but this repo is actually the updated REST based API - which appears to be mostly the same functions as the older API but with less documentation.

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

EBay added a rest API. They still have the old XML one. They sometimes interact in fun ways!!!

Even 40 years ago encoding things as free text such as this would have been very bad practice.

And don't get me started on encoding multiple items in a single csv column.

Documents will only be good if there is a strong review process by someone other than the devs who wrote the code. MS used to do that to a great degree until fairly recently. Amazon isn't big on TPMs unfortunately.

so these convoluted hiring hazing quizzes realy don't help " I'm shocked, shocked "

I agree with you but that's not unique to Amazon and nor is it a modern problem. More than 20 years ago, I was pissing in empty bottles next to trucks to make my quotas when throwing boxes for FedEx when I was in university. Ditto when I threw boxes at an Abercrombie & Fitch / Hollister distribution warehouse in university. Same story when I worked construction jobs. Same story when I was a teenager, picking corn and beans by hand in the fields near where I grew up. In fact, of the over a dozen manual labor jobs I've had in my life, the only one where I had convenient and frequent access to a restroom facility was a Thomson Consumer Electronics glass factory.

It's been surprising to see how much better people tend to view Amazon vs. Walmart when Amazon is just the next iteration of megacorp retail consolidation in the same vein with an increasingly horrible record of employee exploitation and abuse.

fair but wildly off-topic.

They get away with it because there is no competition. Well there is eBay, but that has an even worse api.

What are you doing to do? Deal with it or decide to not sell your products?

This is my experience, too. I was a new paying user of Amazon Seller Central, confused by the UI and missing documentation, and they simply ignored my ticket.

This actual exists in some places! Check out moduledocs and "doctests" for languages like Elixir. Was something really cool I liked while I have been learning Elixir.

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.

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

Use contracts and propery-based testing. See Hypothesis library in Python (and other laguages). I wrote a library for contracts in Python (http://github.com/Parquery/icontract, see its readme for further references to other libraries).

This is why I prefer to link to actual code in the repo, in an examples directory, which gets compiled during every build.

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.

obligatory "Rust docs can do this"[0] (quite a nice feature tbh).

[0] https://doc.rust-lang.org/rustdoc/documentation-tests.html

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

Comes standard with Rust

Typo in the example? Mr. One-Up here to bring up HP Fortify’s (static analysis tool) API that had typos in the named parameters. But no typo in the named return value. So you would pass in a value for “fuebar”, and then look for “foobar” on the return. As one of many examples.

All you've done is deploy the existing documentation on your own service and change the links on the GitHub repository to point to your service rather than the GitHub documentation (with no indication of how one would keep this in sync with updates).

Sure, it makes navigating this version of the docs slightly easier, but this doesn't seem to be a good-faith attempt at actually improving the documentation so much as promoting your service.

You should be transparent about the fact that contour.so is your product.

Also, I do not think contour.so addresses any of the real concerns about the documentation.

that website breaks my browser back button

It’s worth fuck all because sellers will bang their head on a wall for 2 months until they work it out because they have no other option.

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.

This post is talking about said new RESTful API.

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.

Some fleeting sense of pride in one's work, I would suppose. But yeah that doesn't move those dashboards.

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.

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.