If you have had the misfortune of interacting with Amazon seller central or vendor central as a merchant, as I sadly have. This won’t come as a surprise, it boggles my mind how bad, buggy and user hostile that software is. The fact that Amazon keeps moving forward with their IT estate as bad as it is amazes me.
“This is the worst documentation I have ever seen in my life”
61–70 of 112 posts
Re: “This is the worst documentation I have ever seen in my life”
#62And now Amazon have locked the issue so others can't agree with the original poster. Don't fix the problem just fix the person who mentions it !
Re: “This is the worst documentation I have ever seen in my life”
#63I hope the software industry realizes that good documentation is more valuable than good code. Code is transient, and even good code today will be called techdebt tomorrow when the next language or framework or library shows up. But bad documentation impedes your ability to write good code, your ability to work with other parts of the organization, and your ability to grow your business by having outsiders integate with you (as in this case): it also has the effect of turning code into techdebt, by causing people to write new implementations of code they otherwise could have used, because they have no documentation for it.
One step we could take is in hiring. When interviewing developers, let's ask them to write documentation, not just code.
Re: “This is the worst documentation I have ever seen in my life”
#64Just 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…
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.
Re: “This is the worst documentation I have ever seen in my life”
#65I 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.
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.
That's because we've had a good 15 years of tweets and articles from tech luminaries and op-ed writers that used their shopping experience at Amazon as a stick to beat Walmart with. For the most part, those thought pieces have always been written by white-collar people who had no idea of the human toll that two-day shipping takes.
Their entire experience w/ Amazon starts at the website and ends with the brown box with the smile on it.
Re: “This is the worst documentation I have ever seen in my life”
#66We 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.
My company is currently trialing this with the Open API Spec. The workflow at a high level:
1) Make code changes to a specific microservice. (note: The Open API Spec also lives in code.)
2) CI/CD pipelines get triggered.
3) New microservice is built.
4) Call every REST endpoint defined in the microservice's Open API Spec and validate it using the example requests/responses.
5) If successful, regenerate the API documentation from the Open API Spec.
This ensures that our documentation and services will stay inline with each other.
Re: “This is the worst documentation I have ever seen in my life”
#67I once worked with a financial product that used CORBA for distributed processing. One chapter of the dev guide had examples of use that were... Let's say not possible with CORBA... I opened a ticket with the vendor, because of course we were paying a large purchase percentage maint fee. I was not part of vendor selection. The official response from the vendor was "please remove that chapter from the dev guide.". Beautiful!
Before you hate on CORBA I submit that my masters thesis was based on CORBA for distributed processing and that, "horror of horrors" it had solutions for many of today's issues.. albeit implemented with tooling that was lacking. Anyone for a game of what vendors RPC implementation this is based on packet dumps?
Re: “This is the worst documentation I have ever seen in my life”
#68Those directed graph traversal interview questions really contributed to the quality of these documents.
so these convoluted hiring hazing quizzes realy don't help " I'm shocked, shocked "
Re: “This is the worst documentation I have ever seen in my life”
#69~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...
[deleted]
Re: “This is the worst documentation I have ever seen in my life”
#70Earlier 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... .
Not the docs, the library code is (for the most part) automatically generated
This is actually a good example of how the thing works, you have to use MessageBody as an argument name to send the message. Or use the Entries argument
Those names and that usage style are far from Pythonic