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

81–90 of 112 posts

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

#81

Post by ArchOversight »

raverbashing wrote: post #70
glaucon wrote: post #56

Earlier quoted context omitted.

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

They map to the underlying JSON calls that are made. It's like they took the top-level keys of the JSON and made them kwargs in the Python.

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

#82

Post by bredren »

Raphmedia wrote: post #41
bluntfang wrote: post #30

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.

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

I 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

- ?

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

#83

Post by brianwawok »

paradisevoicez wrote: post #17
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…

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.

It seems like more or less a wrapper around the MWS api. Many calls are identical.

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

#84

Post by brianwawok »

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…

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

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

#85

Post by hermanradtke »

sonny3690 wrote: post #74

I 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 The Deployed 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…

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.

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

#86

Post by kakwa_ »

crypteasy wrote: post #66
qayxc wrote: post #23

Earlier quoted context omitted.

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

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

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.

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

#88

Post by sn_master »

jordache wrote: post #27

Those directed graph traversal interview questions really contributed to the quality of these documents.

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.

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

#89

Post by sn_master »

VWWHFSfQ wrote: post #45
m1gu3l wrote: post #15

Earlier quoted context omitted.

fair but wildly off-topic.

no no the topic of this post is "amazon bad"

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

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

#90

Post by rpm91 »

sonny3690 wrote: post #74

I 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 The Deployed 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…

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.

Post reply on HN