back to Jitbit Blog home About this blog

Fix The Damn Docs

by Alex Yumashev · Updated Sep 9 2019

We blog a lot about customer service here.

Best practices, useful metrics, "how X helps with this" and "how Y helps with that", blah-blah, yada-yada...

But here's the best customer service advice ever.

The one that will cut your costs, boost conversions, close more sales and improve [insert whatever buzzwordy metric here] by friggin 99%

Go Fix Your Docs

No, seriously, it amazes me how companies are investing millions in fancy customer service gimmicks, like building rule-based chatbots, hacking some cloud-based AI-backed NLP-powered FAQ-suggestions engine or some neural-network-backed phone answering machines...

Instead of simply fixing their half-assed user manual or updating the outdated API docs first.

* here and onward - actual screenshots of faulty docs posted by Redditors.

Docs shouldn't be an afterthought. After all, better help documentation means fewer support emails. Fewer support emails means less distraction for your team. And your team can concentrate on moving your product forward instead of explaining how a basic feature works for the 1000th time.

According to Forrester research, self-service is on the rise. Not only customers search for answers online, they actually prefer to use self-service instead of talking to a person. Especially if your product is for developers or sysadmins. We're introverts FFS, please don't make us call you.

Documentation never sleeps. It's available 24/7. It needs no salary. And properly organizing and categorizing it helps people learn about unfamiliar features, making them use your product even more and discover new use-cases.

But still so many companies are ignoring this. Docs are being written on the fly, after an app has already been launched. Or not written at all. Because docs are for pussies, right? Let's measure "customer happiness" instead. Let's send out a ridiculous survey to find out if they are "extremely satisfied", "somewhat satisfied" or "somewhat dissatisfied".

I don't want to point any fingers, but... well, I actually do want to point fingers. I'm talking about you, Salesforce. I'm talking about you, Microsoft. I'm talking about you, Atlassian. I'm talking about you, Facebook. And many many others.

I'm talking about all the companies who decided they're all "agile" now and should release a new version every week - just without updating the docs.

I'm talking about all the companies who decided that "the old uncool API" should be deprecated but "the new cool API" barely has any documentation.

Bad habit?

Maybe it's all coming from the non-digital age, when most sales were "one time". Here's my favorite picture from Kathy Sierra to illustrate this:

We cant afford that any more. These days everything is software. Everything is becoming a SaaS - a subscription service of some sort. Even the old-school traditional stuff you'd never thought of.

Like, cars.

Last year Volvo's "on call" network went down in Europe, making it impossible to pre-heat your car using the mobile app (which is a pretty huge deal if you live in northern Europe where winters are long, dark and cold). Hundreds of customers started tweeting at Volvo... And you know what Vovlo's response was? "Please contact your local dealership". No, Volvo, you're a software company now. Join the club. I'm paying extra for this service, so you're literally a SaaS provider now.

But enough with the rant.

Handy tools to help build great docs

Here are some tools that help build great docs (we're not affiliated in any way):

http://ricostacruz.com/flatdoc/ - a tiny JS file that renders beautiful documentation pages from markdown files.

https://readthedocs.org/ - a nice doc hosting option, can import from git/mercurial repos etc.

https://docusaurus.io/ - self-hosted Node-based docs engine

https://en.wikipedia.org/wiki/Comparison_of_documentation_generators - Wikipedia list of documentation generators (from source codes)

https://docsify.js.org/ - another self-hosted help site generator

https://www.gitbook.com/ - paid (freemium) tool for docs authoring and hosting

(please share your favorite tools in the comments, I will add them to the post)

P.S. A note about open source projects

I'm mostly talking about commercial software. Open source is different in its altruistic nature. We should be grateful to people who decided to spent their free time building a software tool that we get to use for free.

So I'm more or less OK with this:

Unless the project is backed by Facebook, Google or Microsoft though, which makes it a whole different story. Corporations are backing open source for a reason. Which can be marketing, attracting talent, reshaping the market shares, hooking devs on their stack. "If something is free means you are the product" - and I'm totally OK with that.

But darn it, Microsoft, why are the ML.NET docs always a couple of releases behind?!