The Importance of Software Documentation

They just released my YouTube podcast!

“Why is documentation important, and how we can make it better”

(If the embedded link fails, navigate to https://youtu.be/Ok8PwWbvZRA?si=UOlRoA8Qgg8MdDcw.)

In this podcast with @ray Paik of @pingcap, I describe my lessons learned from a decade of writing for developers. I have my own take on what makes great product docs. We talked about a number of things:

• Target audiences: the developer and the sysadmin. Good docs don’t overload users. Great docs help these audiences start using a product in minutes!

• The hierarchy of documentation, from code comments, to READMEs, to blog posts, to actual product docs.

• Readability: New software is complicated enough. If you add unneeded complicated words, that encourages readers to look at competitors.

• Brevity: How you should avoid too many details. Good use case docs include just the information that the reader needs to get your software to work. Anything else can overload busy readers.

• Hackathons. Some hackathons get lost in correcting spelling mistakes. And that’s not worth it for the company that’s running the hackathon. However, when writers test product instructions, that’s as good as gold. We know that excellent docs help users in minutes. And that can make the difference in sales.

— Writers who test product instructions prove their worth to the company during the hackathon.

• Involving writers in development. Writers who are involved up-front create better docs. (I forgot to mention how this is “agile” ;))

• The power of open source documentation. If your documentation tools are open source, it’s easier to get help from the community.

• The impact of AI: How you can train docs on authoritative sources to avoid the problem of “Garbage In, Garbage Out” (GIGO).

During the interview, I wore a Sun Developer Network tee. While I never worked for Sun, I’m proud of my association with people who worked there, especially at @ForgeRock.