I would prefer reading the OpenAPI spec for an API - which is in a standardized format and has easily searchable/skip-able sections, like schemas, endpoints, etc. An interactive tutorial that you mostly read from beginning to end is not convenient for devs - we want to find things within a few seconds of hitting the docs page.
The point of the article is not to _replace_ the spec. The point of the "four-document types" model is that different document types fit different use-cases.
The "HTTP" format proposed in the article is the same we use with Hurl [1], an Open Source HTTP CLI based on plain text.
POST http://httpbingo.org/anything/chat
content-type: application/json
{
"message": "Hello!"
}
We extend it a bit to add checks on response, and add request chaining, but it's basically HTTP 1.x as this article shows it. A lot of others tools have the same idea, with minor differences:
One thing that trips me up when I see this 4 quadrant structure for documentation is when to go with a tutorial and when to go with a how-to. Curious how others delineate between those.
Tutorial takes you from an exact point A to an exact point B. Guide is much "looser" and just describes the general steps to get something done, without making any type of guarantee of being able to take you exactly from A to B. Mostly out of acknowledgment that the real-world is messy and everyone is going to have a slightly different system. Tutorial is for people starting from scratch or who want a gentle hands-on intro to your thing, guide is for people who are doing messy integration work with existing systems. It's not a perfect delineator but it'll get you most of the way there...
Tutorial is a Getting Started, with no specific goal other than to serve as a general hands-on introduction. It does not assume any prior experience with the tool/product.
How-to(s) is a cookbook, targeting specific use cases, and may not particularly cater to novices.
OpenAPI is more than just documentation generation, it’s also used for runtime time validation and codegen for both client and server stubs. I’d argue that what’s discussed in this article can complement OpenAPI but doesn’t replace it.
OpenAPI has great affordances for providing examples along with pertinent documentation sections. Many OpenAPI UIs provide ways to execute those examples or other interactive ways to populate and try requests. These could surely be better honed for the how-to guide style of documentation! But I think that’s probably a better place to start for people who are starting at, and looking to go beyond, what OpenAPI currently provides.
Readit News
This is Diátaxis: https://diataxis.fr/
- Hurl (I'm one of the maintainer) https://hurl.dev
- HTTP Client https://www.jetbrains.com/help/idea/http-client-in-product-c...
- httpYac https://httpyac.github.io
- restclient.el https://github.com/pashky/restclient.el
- REST Client https://github.com/Huachao/vscode-restclient
- verb https://github.com/federicotdn/verb
And many more...
Worth noting, other tools have taken the YAML route (like Step CI https://stepci.com), JavaScript (k6 https://k6.io/docs/using-k6/http-requests/)... I'm biased of course, I've a tiny preference for the simple plain text format.
And of course, there are also GUI application (Postman, Insomnia, RecipeUI amon others)
[1]: https://hurl.dev
How-to(s) is a cookbook, targeting specific use cases, and may not particularly cater to novices.
Following this standard, a tutorial may contain a simpler or more contrived example; it may contain things you'd never do in production.
The idea of an interactive tutorial is great, but as others have mentioned, likely very difficult to maintain over time.
If your specification is self rewriting, can be tested and can be used to generate docs then maintenance costs plummet.
Long time ago at Klarna we used this tool: https://github.com/for-GET/katt Here's an example: https://github.com/for-GET/katt/blob/master/doc/example-http...