Let's talk Documentation

Discussions
#1

Those of you with a technical product, let’s talk documentation!

At Perch our customers range from experienced PHP developers, through to the majority who are good front-end developers but not so experienced with PHP, then through to a sizable group who don’t really know HTML and CSS all that well.

The docs have to help them all, and while a lot of people cite our documentation as being great, we sometimes get in quick succession one customer telling us how terrible our docs are and another singing their praises.

Perch does require that you know HTML, so we make that basic assumption in the docs. The people who tell us our docs are terrible tend to be those who rely on a wysiwyg editor for HTML and really aren’t our ideal customer. However there is still a huge difference between customers, and even just in terms of how people learn. I believe there is nothing more annoying than having to watch a video to get info - and yet our videos really cut down support so I know many people find them useful!

In the light of the support discussion this week I just wondered if anyone had found certain things to really help in terms of writing docs for a range of users, or just had used some docs they thought were great. Perhaps some of you just starting out are wondering how best to provide support material?

I don’t see a lot of people talking about documentation and yet doing it well can really cut down the support burden for a small company.

1 Like
#2

My experience has been that many users think documentation for a product is rubbish, unless the information they want is right in their face (no matter how obscure it is). I have two benchmarks for my documentation, which also reflect how they are structured:

  • Can I link to general information pages that will answer questions for new users and give a general overview
  • Do I use the reference documentation myself, and does it provide what I need when developing with the library (rather than for the library).

So my documentation is split into a Manual and a Reference - the first for introductions to topics (how to use the API, options, events, etc) and the second being detailed information about options, apis, etc. I’ve recently switched to this form, and I think its really helped. I get less questions about how to use certain parameters (although as per the other thread, there are plenty of other questions cropping up!). This also helps the range of users since it covers both beginners and those who know what a Javascript object is and want to see what the API is.

Like yourself, I think that using videos to get programming information seems a bit crazy… However, its interesting to hear that it has cut down your support requests! Watching your videos is first on my list for tomorrow morning :-). Any tips for creating them (possibly a discussion for a different thread…)?

Regards,
Allan

#3

I guess the first thing is to realize that most of them won’t read the documentation. No matter how good!

Similarly I split mine into beginning (intro, tutorials etc), reference (covers various topics, including a page for each window) and ‘how do i…?’ (covers all the questions that people frequently ask). For the vast majority of support questions I can just send them a link to the appropriate ‘how do I…?’ page. It seems to work pretty well.

#4

[quote=“Andy, post:3, topic:1653”]
I guess the first thing is to realize that most of them won’t read the documentation. No matter how good!
[/quote]Anyone with apps in production ever try to incorporate links or snippets of documentation within the interface to assist?

#5

Funny, I just realized that I do. I develop SOAP web services; and I place detailed explanation what went wrong and what could be the likely way to fix it into the SOAP Faults returned by my systems.

Granted, this interface is not seen by many people in production, but in development it is seen by quite a lot of people and it actually helps to reduce the number of questions. People do not read complex design documentation, but a timely help entry (even embedded into a SOAP XML) they do read.

#6

The videos help a huge amount for the type of user who is not used to reading technical documentation. We find that a lot of the time we just need to get people started, get something working for them and then they are fine with regular documentation. So we don’t have videos for anything particularly complex, it’s more of the getting started stuff.

I need to do some more but they are time intensive to make. I have a secret weapon in that my 17 year old is a great video editor and so when she is back from college she’s going to help me do a new round of videos and update the ones we have :slight_smile:

All of the tools for recording these things are awful, the best I’ve found is ScreenFlow My process is to script the tutorial. Then record the screen and then record the voiceover - then I send it all to the teenager who edits it together and makes sure the talking matches the actions!

Shorter videos work best and are easier to record and edit too.

#7

Before I chime in, some backstory: We have several server-side products which means that the code is open and can be modified by anyone. Our customers range from not-so-tech-savvy to PHP developers. However, we don’t have an API, so the it’s a bit different kind of situation.

Surely, the “I don’t know anything about PHP, but I want to customize this myself and you have to help me” customers are a huge pain. Since we’re a really small team, it’s not possible to hold the hands of all of them. If they have any questions that aren’t answered in the documentation (Help Center), I answer them and take note. The third time someone asks the same question I add it to the Help Center. This results in a lot of articles, but it really cut down support requests for me. Judging from the Google Analytics stats, people read these articles and they (obviously) find the solutions without having to contact us.

Of course, your product is different, but I don’t think you have to teach anyone HTML or CSS or PHP. If they want to use an API, they have to teach themselves those things first. If I were you, I wouldn’t try to hold their hands. It might sound like you’d be letting go from a lot of customers, but if these customers are a huge support burden, then maybe they aren’t worth the effort.

[…] I just wondered if anyone had found certain things to really help in terms of writing docs for a range of users, or just had used some docs they thought were great.

I definitely don’t have your experience, but when I write our docs, I assume that people don’t know how to copy a file :smile: Especially when the article is about modifying code, I try to explain it step-by-step and make the code modification foolproof. It might be annoying for more advanced users, but at least the ones that ask more questions are happy. If the range of users is too broad, you might, for example, separate the docs into “Basic” and “Advanced”.

I hope this is helpful in some way. :smile:

#8

I think that given the typical quality of docs in your average software product you can’t really blame users for not reading.

Docs are often written hastily and are usually not well maintained. They’re tucked away in “knowledge base” systems that offer up an avalanche of articles and no quick answers.

Seriously, think of the term “Knowledge Base”. Could we come up with a more unappealing term for helpful content?

As @rachelandrew says, this is something nobody talks about. Most businesses don’t see the value in good docs, and so the quality suffers. As a result people don’t read them, and the cycle continues.

However when docs are good, a good chunk of users do read/skim them and benefit from them. I know every time I improve my docs support requests go down. So somebody is reading something!

Yes. I am adding rich tool-tips on every one of my inputs. By that I mean a carefully written sentence or three that orients the user as they try to figure out what they should enter, where it’s going to show up, and why it matters. The tooltip appears when user hovers over a question mark next to an input. When necessary the tooltip includes a link to an article that explains things further in my User’s Guide.

Note this is not one of those “check box to turn $WIDGETX on.” kind of “tip”. I assume my users know how to use a checkbox. Instead the tooltip tries to demystify what $WIDGETX is and when and how it is most commonly used.

I find this arrangement to be the most effective thing I’ve come up with so far. It’s a way of providing very relevant help at exactly the right time. I’ve had very few support questions from people regarding features that are equipped with these.

It’s also a way to funnel people to the actual full-length docs thanks to the links in the the tool-tips.

The key though is to write these tool tips from the user’s point of view, not the programmer’s. This is true for all docs but particularly hard here because their content is stored in source code. (eek, I know, but that’s the way it is.)

1 Like
#9

I’ve found videos can be great for beginners who don’t know all the things that experienced programmers take for granted. This type of detail is easily forgotten in written documentation but ends up being super frustrating for beginners. For example, look at how popular railscast (http://railscasts.com) and egghead (https://egghead.io) videos are.

For some tips on creating video, check out this guide from Wistia - http://wistia.com/learning/making-better-help-videos

#10

Exactly. So, instead of assuming that nobody reads the manual and throwing the blame on users, it makes more sense to me to think what we could improve.

The problem with manuals is that they lack context. A manual doesn’t solve a customer’s current problem/question. It’s just a load of information and there is no motivation for users to read it.

By contrast, In-place information (like the tooltips you mentioned), tutorials or answers to specific questions are more likely to be read, IMHO.

That depends. If you have a good search algorithm in place and the questions use the words that customers do (i.e. you have stats about the search and you monitor search terms), answers can be quite easy to find.