Minimum Viable Documentation for Developers

So much to do, so little time!

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

Last modified April.04.2024