“This is the worst documentation I have ever seen in my life”
1–10 of 112 posts
Re: “This is the worst documentation I have ever seen in my life”
#2We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
Re: “This is the worst documentation I have ever seen in my life”
#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
// so we'll just parse each item as a regex. Thanks Amazon.
Re: “This is the worst documentation I have ever seen in my life”
#4Having coded with MWS, I can confirm. I don't remember the details but there was a typo in one of the PHP examples leading all API calls to fail. Easily fixed but should I really have to edit the provided example code to get something working?
Re: “This is the worst documentation I have ever seen in my life”
#5Just 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 in the early to mid 2000's when e-commerce was taking off, so they are architected using the tech and philosophies from back then (XML, SOAP, SOA, etc) however we are no in 2020 and people expect up to date modern interfaces and APIs, and communication protocols; but these API's can't be shut down or risk major breaking changes because so much other stuff is built on top of them.
Really at the core of the day the problem is that so much crap on the Web is considered ephemeral and so many business come and go so quickly that the question of what to do about legacy tech on the web isn't much of an issue because things don't last long enough to be legacy. The exceptions are some of the e-commerce APIs of these big tech companies such as Ebay, and Amazon that managed to thrive, but now are faced with a challenge most people never are of how to migrate legacy web services.
EDIT: Updated appearantly I was not reading closely enough, this is not for the MWS API but the new REST version of their Seller APIs. That being said I'd still be willing to wager a pretty penny they slapped together a REST-to-XML translation layer on top of the MWS APIs and called it a day.
Re: “This is the worst documentation I have ever seen in my life”
#6We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
This is why I prefer to link to actual code in the repo, in an examples directory, which gets compiled during every build.
Re: “This is the worst documentation I have ever seen in my life”
#7I 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.
Re: “This is the worst documentation I have ever seen in my life”
#8We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
obligatory "Rust docs can do this"[0] (quite a nice feature tbh).
[0] https://doc.rust-lang.org/rustdoc/documentation-tests.html
Re: “This is the worst documentation I have ever seen in my life”
#9We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
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.
Re: “This is the worst documentation I have ever seen in my life”
#10Having coded with MWS, I can confirm. I don't remember the details but there was a typo in one of the PHP examples leading all API calls to fail. Easily fixed but should I really have to edit the provided example code to get something working?
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.