[KV] This documentation stinks

[bn-l]

Existing documentation URL(s)

This is just one example, and it's unfortunate that it's a relatively minor one but it was the decider on whether to post this complaint issue (and I don't want to single out the particular writer unfairly--this issue is prevalent throughout the "documentation" for workers):

https://developers.cloudflare.com/kv/api/delete-key-value-pairs/

Does this throw if the key doesn't exist? What does it return?

Again this is just one tiny example. I get the feeling that these docs were thrown together by a lot of quick hires / contractors and it is the deciding factor on whether I will recommend workers or use them in my own products. I can understand though, workers have only been around for SEVEN years.

Why is there no standard long-form API document? Why do I need to hunt around in examples, tutorials (always not updated to the latest way of doing things) to find crucial bits of information?

"code as documentation" here also doesn't work: https://github.com/cloudflare/workerd/blob/9bb3e21cd95acb9f248409a12e6bfa10caafa86f/src/workerd/api/kv.c%2B%2B#L425

Workers is a very cool idea that is let down massively by its documentation.

I at @kentonv because it's a username I recognise from hackernews.

What changes are you suggesting?

Better documentation

Additional information

No response

[kentonv]

A bit blunt but some fair points, we really ought to be generating API reference docs more systematically, starting from our TypeScript types, probably even generated from doc comments in those types (so that vscode tooltips can also show the same docs, etc.).

Of course you still need human judgment to decide what details need to be covered in the description (e.g. "does delete throw an exception if the key doesn't exist?") but with more auto-generated docs it'll be easier to get the core developers to take ownership of such content, whereas today the reference docs tend to be owned by the same people that write the overview docs and design the overall organization of the site. I think core developers are the best people to write API reference docs, but often not the best people to write overviews.

[crwaters16]

Quick note on the API reference docs - those live here: https://developers.cloudflare.com/api and are generated from our schemas. We're also working with our internal teams to help improve the API reference descriptions that get written so they're easy to read and understandable.

I know it doesn't solve all of your problems, and it sucks that the reference docs aren't where you may've expected to find them. The docs team is working to bring a tighter integration between our long-form content and the API reference so this experience gets better.

[kentonv]

@crwaters16 This user is complaining specifically about the Workers JavaScript runtime APIs, not the Cloudflare control plain REST API. The Workers runtime APIs unfortunately do not have auto-generated documentation today.