Why your developers should do software documentation

Marybeth Alexander | March 27, 2014

The Catalyst: What you learn from writing software documentation

As a knowledge base software company, it’s pretty embarrassing that, until two days ago, we did not have any articles in our own knowledge base. What can I say? Starting a knowledge base is hard.

Two days later, our lead developer Pete Grigg threw on his headphones and knocked out six knowledge base articles. In the midst of his writing extravaganza, he took off his headphones, turned to me, and said, “We really need a file library”.

The File Library: A feature born from dogfooding and documentation

Now, Pete’s experience was a form of dogfooding (or eating your own dog food), a term commonly used when software companies use their own product. Using your own product creates a tight feedback loop that allows you to quickly identify issues and better understand what direction the product needs to go. It’s being your own customer!

Software documentation generally requires that you use the product which you are writing about, so essentially documentation becomes a form of dogfooding. However, often times the people writing the documentation aren’t the same people building the product.

Luckily for us, Pete is the lead developer and he spent a good part of Tuesday actually using his product. As he started documenting the application, he quickly learned how his dog food tasted. According to him….

“The file thing made no sense. We need people to upload things to our servers so they display quickly, and trying to explain that you need to upload an image into an article to host it locally was a bad idea. It came down to documenting a shitty work around or fixing the issue.”

So what did Sheriff Pete decide? Fix the issue, of course! Over the past two days, Pete built a file library and vastly improved the experience of uploading images and files to your knowledge base articles.

The file library is AWESOME and the process of adding images and files to your documentation is basically a gazillion times easier. Thanks to Sheriff Pete, you can now…

• Quickly and easily insert images and files into your articles

• Add images from your library or upload new ones

• Manage your images and files in your knowledge base file library

• Upload multiple images into your library in bulk

And what problems did he fix along the way? SO MANY, but now…

• You can upload multiple images into an article without having to save

• You can view your uploaded images without having to save

• You can insert images and files in Source (HTML) mode

• Non-image files will now insert as an href rather than an image tag

And the customer feedback so far has been amazing. After finding out about the update, the following chat conversation ensued:

Customer: I AM LOSING MY MIND
Pete Grigg: IN A GOOD WAY OR A BAD WAY?
Customer: GREAT WAY
Customer: STOKED
Pete Grigg: YAY!!!
Marybeth Alexander: YAY!!!!
Customer: GUITAR SOLO!

The Takeaway: Writing software documentation is a great way to drive development

When talking about knowledge bases and software documentation, people are quick to laud the obvious benefits: reduced support, happier customers, staff knowledge sharing, and more. But there is a huge benefit in the act of writing the documentation: using your own product as a customer!

When you write about your product, you are (1) eating your own dog food and (2) seeing your product through the eyes of the customer. If your developers actually have to use your product AND explain it to customers, bugs will get fixed faster and useful features will get deployed.

So should you have your developers write your software documentation? Am I crazy? Let me know in the comments!

{{snippet.MarybethAlexander}}

{{snippet.Disqus}}