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

21–30 of 112 posts

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

#21

Post by bfieidhbrjr »

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

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

#22

Post by breck »

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

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

#23

Post by qayxc »

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.

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

#24

Post by tannhaeuser »

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

That looks like putting "" and "" 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 "" tags (but it still won't work satisfactorily with your example data).

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

#26

Post by gleenn »

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

Xml is an open standard man, just pretend your Neo from the Matrix reading the screen saver

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

#28

Post by qayxc »

twblalock wrote: post #6
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.

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

Unfortunately that doesn't help if the documentation is written by a different team and in a different format.

Getting out of sync happens very quickly if docs aren't generated from source and aren't an integral part of the release process.

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

#29

Post by jancsika »

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 was kind of hoping for:

:)

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

#30

Post by bluntfang »

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.

Post reply on HN