10 ms·
“This is the worst documentation I have ever seen in my life”
- MattGaiser 6y agoWe need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
- twblalock 6y agoThis is why I prefer to link to actual code in the repo, in an examples directory, which gets compiled during every build.
- dgb23 6y agoThis is not only simple and comprehensive but also doesn't require any special support from the tooling or language. Love it!
- qayxc 6y agoUnfortunately 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.
- mijoharas 6y agoobligatory "Rust docs can do this"[0] (quite a nice feature tbh). [0] https://doc.rust-lang.org/rustdoc/documentation-tests.html https://doc.rust-lang.org/rustdoc/documentation-tests.html
- m45t3r 6y agoPython can too, and I think most other languages are inspired by it. https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html
- bussierem 6y agoThis 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.
- johnc1231 6y agoWe do this for our project (https://hail.is https://hail.is) and it's a game changer. Saves so much time and so many bug reports.
- pdimitar 6y agoCan you specify how are you doing it exactly? Very interested.
- forsaken 6y agoSphinx supports this for Python: https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html https://www.sphinx-doc.org/en/master/usage/extensions/doctes...
- m45t3r 6y agoThis is actually something from Python's stdlib: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html Really underrated.
- TT3351 6y agoI seem to recall a talk given at one point that demonstrated a scheme that would reverse engineer functions out of whole cloth based only on docstrings and doctests, but of course I can't find it now.
- MattGaiser 6y agoMy job is mostly Python. Did not know this existed.
- qayxc 6y agoThat'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.
- crypteasy 6y agoMy 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.
- kakwa_ 6y agoIt's far less extensive than what you presented, but on the current project we are working on at work, we are using https://github.com/swaggo/swag https://github.com/swaggo/swag It's somewhat specific to golang but so far it has been relatively good for us. The spec is directly next to the code as code comments, so it has far more chances to get updated when changes are made compared to an external documentation. Also, the payloads and responses are directly derived from the Golang structs, so, at least on that aspect, changes in the code are automatically reflected in the spec (apart for description and examples). We also put the interactive documentation directly in our API under /doc. It is a useful tool for developers when implementing a new url/handler or modifying an existing one. It also creates incentives to keep the documentation matching. Overall, we had very few mismatches between the spec and the actual implementation overall, despite not having deeply tested it (be it manually or automatically). Apart from one or two mismatches that were fixed quickly, I was able to take the spec, generate client libraries from it (swagger-codegen), and use them for quite extensive demos without issues. We are still early in the project (not in production yet), and there are definitely some aspects we need to improve (integration/automated tests to be sure doc and code are 100% matching) or to completely figure out (ex: how to handle several versions of the same API). But overall, using swaggo/swag has been a pleasant experience.
- FeepingCreature 6y agoIf 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.
- mristin 6y agoUse 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 http://github.com/Parquery/icontract, see its readme for further references to other libraries).
- bradwood 6y agoComes standard with Rust
- llimllib 6y ago~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: // <Batch>batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 </Batch> // and an incomplete batch like: // <Batch>batchid=363778361 status=In Progress </Batch> // so we'll just parse each item as a regex. Thanks Amazon. The documentation at the time was just a post on a forum, that later got removed, so it no longer exists at all but this was just one of many horrors.
- bfieidhbrjr 6y agoreminds 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>
- gleenn 6y agoXml is an open standard man, just pretend your Neo from the Matrix reading the screen saver
- deleted 6y ago[deleted]
- kingaillas 6y agoI 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 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.
- ethbr0 6y agoIn all fairness, during the first XML migration, I'm sure internal MS folks were just as baffled at the previous format.
- ikeboy 6y agoHaving 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?
- mikestew 6y agoTypo 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.
- hpoe 6y agoJust 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.
- corbin 6y agoAgree 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.
- paradisevoicez 6y agoThis 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.
- brianwawok 6y agoIt seems like more or less a wrapper around the MWS api. Many calls are identical.
- hmaxwell 6y agoI 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.
- m1gu3l 6y agofair but wildly off-topic.
- VWWHFSfQ 6y agono no the topic of this post is "amazon bad"
- sn_master 6y agoamazon technical != amazon retail and the conditions have only been improving, and with more robots, the number of warehouse workers will only keep getting less. drivers on the other hand is a different story..
- pengaru 6y agoOff-topic I'll give you, but wildly? That strikes me as wildly hyperbolic.
- pengaru 6y agoIt'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.
- rchaud 6y agoThat'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.
- schappim 6y agoI've written code against Amazon's MWS (btw they have a brand new RESTful API available now) and just for the record the eBay, USPS APIs are similarly "not stellar".
- loufe 6y agoThis post is talking about said new RESTful API.
- hprotagonist 6y agocan i introduce you to my friend openCV? :/
- nograpes 6y agoI 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.
- nl 6y agoMatplotlib...
- hprotagonist 6y agomatplotlib is esoteric ( if you didn’t already have psychic scars from matlab experience and thus already speak their esolang), but at least it documents kwargs and links out to source and doesn’t just give you out of date snippets in broken english. OpenCV can’t be assed to link out to source, and also won’t even bother telling you what the function signatures are, what the names of all the methods are, or anything else useful.
- perfectstorm 6y agois it funny that when i first read the title i thought the author was talking about Apple's Swift documentation? I suppose funny is not the correct word - more like sad.
- jordache 6y agoThose directed graph traversal interview questions really contributed to the quality of these documents.
- walshemj 6y agoso these convoluted hiring hazing quizzes realy don't help " I'm shocked, shocked "
- sn_master 6y agoDocuments 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.
- bluntfang 6y agoI 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.
- Raphmedia 6y agoI 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.
- bredren 6y agoI wonder at the potential competitive points to Amazon. If you could largely copy logistical, reliability and marketplace features what would allow someone to start competing using a similar model? - Seller relations and developer experience - Marketplace and human resource ethics - ?
- bredren 6y agoI 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.
- deleted 6y ago[deleted]
- odiroot 6y agoHeh. And this is actually an improvement. The previous/legacy MWS API was actually way worse. Though the documentation may have been a bit more coherent.
- asciimike 6y agoWell, at least it's not EDI...
- skohan 6y agoI always thought AWS has horrible documentation because the incentive structure is to sell you on premium support.
- sequoia 6y agoSeems that API documentation (in this case) is not terribly important to the bottom line :) (So why should the bother fixing it?)
- djohnston 6y agoSome fleeting sense of pride in one's work, I would suppose. But yeah that doesn't move those dashboards.
- mook 6y agoThat only works if the pride would be induced in the one allocating developer time.
- bredren 6y agoThis 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.
- laumars 6y agoI remember having some Microsoft documentation in the mid 90s for using DDE (an early Windows way of passing messages to different running applications). I forget the specifics of how the example code worked but it acted as both a sender and receiver of DDE messages and did so by executing itself. I remember spending a good 30 minutes trying to work out how the example worked before giving up and doing the classic “let’s just run it and see what happens” approach. The example code from Microsoft turned out to be a fork bomb and it quickly crashed my machine. It took me a long time to trust Microsoft documentation again after that incident.
- wcarron 6y agoAmazon has locked the discussion as 'too heated' and then closed it. I am not even remotely impacted by these issues but that is absolutely hilarious.
- deleted 6y ago[deleted]
- deleted 6y ago[deleted]
- simonbarker87 6y agoIf 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.
- mleonhard 6y agoThis 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.
- PurpleFoxy 6y agoThey 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?
- simonbarker87 6y agoI ran a small manufacturing business that listed on Amazon in both seller and vendor central. I was just interacting with it as a ”common user” for 5 years. Never tried to develop against the API - we did about £300,000 per year through the platforms.
- glaucon 6y agoAnd 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 !
- geofft 6y agoI 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.
- PurpleFoxy 6y agoIt’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.
- aunwick 6y agoI 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?
- sonny3690 6y agoI 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 https://github.com/amzn/selling-partner-api-docs/pull/209 The Deployed Docs: https://docs.contour.so/amzn/selling-partner-api-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!
- hermanradtke 6y agoYou 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.
- rpm91 6y agoAll 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.
- sonny3690 6y agoHolding my two hands up--I saw this post on HN and wanted to help, and using a web app that I've built seemed to be the logical step. But yeah, I could definitely see how it would come across this way, and I'll revert the links back to the PR! Hope that helps.
- VWWHFSfQ 6y agothat website breaks my browser back button
- 6y ago
- markus_zhang 6y agoAt least they are still seeing documentations...
- sn_master 6y ago<cough>Google's SDK C# Documentation</cough>
- akanet 6y agoMy first job out of college was working on Fulfillment by Amazon, which was part of sellers central. The place was a huge mess technically, with like three different authoritative databases, and services constantly trying to second guess each other. Everything was in Java and there was no clear central direction. I think this is probably the main drawback to Bezos' cloud of services mandate.
- rognjen 6y agoSee, the issue is that most probably this person is not Amazon's customer. Their employer is. In which case either Amazon is or isn't important to them. If it is, they can just tell the person to get over it and do their job. If it isn't then they aren't an important customer for Amazon either. In neither case is there any incentive for Amazon to improve. Such is life with a lot of enterprise software in my experience.
- newintellectual 6y agoWell, Amazon solved this problem - by censoring expression of developer dissatisfaction with the abomination. Way to solve a real problem plaguing your client base, Amazon. "@amzn amzn locked as too heated and limited conversation to collaborators 3 hours ago @seanevan seanevan closed this 3 hours ago"
- jlevers 6y agoI'm currently working with this API, and I think that if I didn't have experience with Amazon's old seller API (MWS), I wouldn't even know where to start with this one. As it is, it's taken me many, many hours to figure out how to make this one (sorta) work. (Shameless plug: I wrote detailed walkthroughs of how to get access to[0] and build a basic application with[1] the Selling Partner API). [0] https://jesseevers.com/selling-partner-api-access/ https://jesseevers.com/selling-partner-api-access/ [1] https://jesseevers.com/spapi-first-application/ https://jesseevers.com/spapi-first-application/