Don't miss these: The best writing from API Futures
I’ve been studying up on the writing in API Futures this week.
Ask me about API docs
REST API documentation
Dormant Last read · last published · next check
Read 9 hours ago and current, but nothing has been published for 3 years.
Latest episodes
The future of APIs is about user experience
And how documentation can make a decisive contribution in the user experience
My take-aways after diving into toolchains
Docs as Code is indeed the best tool for many situations, but there are other tools and other situations.
Toolchains have families
Have you used the five most common types?
Anne Gentle: 'How do you keep your authors happy but also make sure your customer gets what they need?'
Anne Gentle has seen numerous changes in the documentation world since she wrote the first edition of “DOCS LIKE CODE.” She’s also made some observations about the things that don’t change.
When docs as code is a big success, this is why
There are situations where the Docs as Code approach is unarguably the best.
A definition for docs as code
The more questions I ask, the more it seems that people have slightly different ideas about the definition of the term "Docs as code."
Knowing the requirements first prevents toolchain misery later
Documentation tools have to fit the circumstances where they're being used, and every company's circumstances are unique.
The trouble began when they changed the documentation tools
Everyone's thinking about new tools -- but why?
Have you read these?
While I’m digging into toolchain research, here are some useful articles that I’ve been meaning to share from my public site.
The cheat sheet for writing Swagger descriptions
OAS3 specs are full of things that need descriptions. Here are some tips for writing them. Always start with the action word. Use the action + object (+ how) pattern consistently for all your descriptions. (Example: "Retrieves a purchase order by ID.")
Test driving the documentation
One of the most effective practices I've found for documentation is something I call test-driving.
Some best practices for technical documentation
Begin with the end in mind. The object of the game is always to save time and reduce frustration for the person reading the documentation.
In documentation, what you leave out is almost as important as what you put in
Principles of technical writing, Part 3
Technical writing is information architecture
"When information is organized well, it's quickly learned and easily remembered. Searching within it seems effortless, because the locations of things are predictable."
The most important part of technical writing
Principles of technical writing, Part 1
Comparing doc tools: Stop doing the apples-to-oranges thing
The best way to assess documentation tools is to analyze the entire toolchain
Coming soon
This is Ask me about API docs, a newsletter about REST API documentation.