The value of quick start guides

I learn by doing. I believe this is true of many software engineers. The quickest way to get to grips with the latest programming language, library or tool is almost always to just get stuck in using it. It’s hard to know WHAT you need to learn about something until you’ve tried using it and realise all the things you could do with it that you don’t yet know how to do.

I am writing this in the middle of setting up this very website. My personal site needed a refresh (by refresh I actually mean building out beyond the “handcrafted” placeholder page I created 5 years ago and never got round to expanding). Having long ago decided that front end development is something I would rather avoid doing unless absolutely necessary, I set out looking for a static site generator that would allow me to get a decent looking site up and running without having to spend hours of tedium learning the latest front end boondoggles. My search led me to Hugo, a popular static site generator written in Go.

At the very centre of the Hugo homepage (at the time of writing) is a bright blue “Quick Start” button. I clicked this, followed the steps and had Hugo installed in a matter of seconds. Then all I had to do was choose a theme (well documented in the quick start guide) and with a few small tweaks of the config file, I had a site! IN LESS THAN FIVE MINUTES. This is the smoothest introduction to a new tool I have had in a long time and, best of all, it allowed me to achieve exactly what I wanted in about half an hour.

Imagine a different scenario. No “Quick Start” button on the home page, just a “Documentation” tab in the top right. You then manage to find some instructions to install the tool but then you don’t know what to do next. You then see another page of documentation that explains how to do X. You want to do a bit of X but not all of X and there’s a lot of unnecessary information about how Y helps X do Z. This confuses you and as you scour the documentation to see what Y and Z are and before you know it you’ve spent an hour reading documentation and you’ve built exactly nothing.

Documentation is often an afterthought in software projects. But for any tool that you actually want people to use, it is easily the single most important part of the project. Personally, for many tasks I would prefer a well documented tool that meets most of my requirements than a tool with poor documentation that meets all my requirements. Good documentation should initiate a hands on experience from the first line as this kind of experience is the quickest way to get a feel for what a tool or framework can do and kickstart the learning process. Then, having been guided through the initial core features of the tool or framework, you can begin to question what else it can do. It is this point where a deep dive into the technical documentation is a less daunting prospect.

Of course, this kind of quick start style docs introduction is common amongst well established tools and frameworks. However, imagine if it was prevalent amongst smaller libraries of code. Often when searching for a library for something, all that exists in the way of documentation is a list of methods exposed by the library. Yes it’s great that the first thing you’re telling me is that your SFTP library exposes a class that accepts a config object with all these configurable timeouts and retries but I just want to instantiate the bloody thing and send a file over the network to see if it’s going to work in my application. You can never go wrong by leading your docs with a good example. People that want to get straight to brass tacks will be more than capable of scrolling right past.

Anyway, I’m mainly writing this so I have a nice first post to go on my new homepage, as shown in the Hugo quick start guide. Just a couple more steps and I’ll be able to get it deployed to the web.