Minimum Viable Documentation for Developers
There’s so much that you can do with API (and other developer documentation). I talked about some of this at a couple of API conferences, the API Strategy & Practice conference in 2018, and API the Docs in 2020.
My premises:
- Documentation is part of the sales cycle, especially when you’re focused on developers.
- For details, see Technical Documentation as Effective Nerd Marketing.
- Developers hate marketing. For more information, see the following book:
- Developer Marketing Does Not Exist.
- Credible developer marketing is based on readable, quickly testable content which addresses real use cases.
- The best way to create content that’s credible for developers is with product documentation.
I have the following criteria for credibility:
- Functionality. Does your solution work for the specified use case?
- Can the reader see how it works “at a glance”?
- Can the reader test your content with minimal prerequisites?
- Visibility. Can the reader “easily” find their use case in your docs?
- Readability. A lot of technical documentation is difficult to read.
- I push a “Flesch-Kincaid” standard for readability of US grade level 9. Some best in breed companies push a grade level of 8. In contrast, the US “Affordable Care Act” (aka “Obamacare”) is written at grade level 13. In contrast, I see a lot of technical and even marketing content that’s even more difficult to read than the Affordable Care Act. (reference: https://shanesnow.com/research/data-reveals-what-reading-level-you-should-write-at)
Pronovix refers to 11 Questions a Developer Portal Needs to Answer. For many, I suggest that’s not realistic, for those with severely limited resources.
In the spirit of readability (with Pronovix’s help), I’ve reduced that to four:
- Landing pages
- Tutorials
- Reference
- Regular blogs (and doc updates)
I discussed these “questions” in my talk to the API the Docs conference in 2020
A number of software companies already have readable software documentation. It’s readable because developers can see how it works “at a glance.” If readers have to take more than about a minute to understand how your product can help them, that’s too much.
And I’ve seen it happen. I’ve been a part of a team selecting partners. The deciding feature was documentation. One company followed most of the principles that I laid out. The other did not.
The product that demonstrated credibility and readability in their product documentation won.