tl;dr For the love of all that’s holy, don’t assume people are using your software because they want to…

Preamble #

I’ve spent some time recently tending to my blog, in the light of feeling like I actually have some interesting things to post about for the first time in ages. I’ve also been indulging in some splendidly geeky bug-fixing and re-visiting a long-term aim to add comments to the site using something other than Disqus (coming soon, hopefully).

As part of this bug-fixing I lost a number of hours this weekend to trying to fix the search page (now ditched in favour of a custom DuckDuckGo search, for reasons that shall become clear below). Adding searches to static blogs is always going to be challenging, but Hugo (https://gohugo.io/) offers a number of alternatives, both open source and commercial (https://gohugo.io/tools/search/). The thing about almost all of the open source options I found is that they involve some variant of node.js and npm, and that’s where the impetus for this post comes in.

In parallel, I’m also doing a lot of work at the moment on documentation with the Google Season of Docs initiative (https://developers.google.com/season-of-docs/), and the nascent TheGoodDocsProject (https://thegooddocsproject.dev/). This has made me look at documentation in a new light, and in particular documentation that shuts down new users or even competent non-experts before they can even get started.

The sordid tale #

A confession first, and a caveat…

Firstly, I don’t really get on with javascript and its progeny, and I don’t use it often enough to get competent with it. Secondly, this post isn’t really about javascript, or node.js, or npm, it’s fairly applicable to a bunch of other tools too (Python and virtual environments and all the variants of package managers springs to mind). Thirdly, I’m not after guidance on how to do this so don’t @ me. This post is about how you should make it easy for people to do their thing because maybe, just maybe, they don’t actually want to be using your software, it’s just a means to an end.

So, since I am not a javascript person, if I come across a situation where I have to use these tools, I want to complete my task quickly and without much fuss, and then get on to the bit I actually want to do, like configure search for my static blog. The process went something along these lines…

1) Installing the basic tools #

I check whether I actually have node.js installed, and come to the conclusion that I’ve done an upgrade on my computer recently enough that I don’t, but that’s fine, it happens a lot so I prepare to install node.js and google the instructions. There seem to be at least three different ways of doing this, all of which appear in the first 4 results when I do a search. I pick the one that involves the least amount of additional yak-shaving and doesn’t involve installing yet another thing called nvm, and go for the approach of sudo apt install nodejs

Then I have to install npm, or do I? Again a quick search gives me two conflicting answers in the first couple of results. One says that installing node.js should have also installed npm, the other says I have to install it separately.

OK, I know how to use a CLI, so I check whether the tools are both installed or not by typing things at the command prompt that look like they should return version numbers or something similar, and repeat the above until they are both installed.

2) Installing the actual modules that I need #

How do I install the modules? Several tell me “simply install…”, which is not good enough. Give me a link to instructions at least. If I know how to do it, I just don’t need to click the link, I’m not going to be mortally offended. I google “installing node modules” and learn about npm install but then there seem to be a number of different parameters I can use. Then there’s the question of whether I install using sudo and whether I install them globally or not. I pick an option, since I’m not given any guidance, and I don’t actually want to do a tutorial on using npm right now, I just want to configure search for my static blog.

3) Running the commands #

Most of the options showed me how to run the command, although one tells me to “use npm scripts” which I have no idea about so I give up on that option as it’s late and I want my tea fairly soon. I pick another approach, and return to the installation steps above to install a different module.

This one shows me how to run the actual command, so I do. Oh no! A strange and esoteric error message! I google it, and go down a rabbit-hole of permissions and conflicting answers (apparently the order I install the modules might be important although that wasn’t stated in the instructions). I try everything, including wiping all my node and npm stuff (which I had to google, just to find how). I never get past the esoteric error, and it’s definitely past tea-time at this point, so I give up on that approach and look at one that says I can use elasticsearch instead.

4) Diverting to use elasticsearch #

Luckily I’m relatively familiar with installing elasticsearch as I use it for GeoNetwork, so I’m in the enviable position of being able to do this fairly easily, but I appreciate not everyone is in this situation. Happily, the instructions for loading the search indices are good. Before I know it, I have a fully functioning elasticsearch running on an AWS Small Instance, and available under a sub-domain of my blog. Unfortunately, at that point the instructions stop, and I never find out how to actually build a search form in my blog that can communicate with elasticsearch. Yes, of course I google it, but the one answer I find (https://discourse.gohugo.io/t/how-to-add-a-search-box-backed-by-elasticsearch/17064) scares me, so I abandon that as I don’t want to build a middleware platform, I just want to configure search for my static blog. So I shut down my server and go and have tea.

5) Giving up and choosing a completely different approach #

To cut a long story short, at this point I was so discouraged that I ditched the idea of a nice search page and implemented a duckduckgo search box instead (https://duckduckgo.com/search_box). It’s not as elegant and I don’t like the way it looks, but it does the job, and the instructions were simple and accurate. The most difficult thing was finding out which file I needed to add the code into.

I gave up on the other options because the instructions were incomplete and assumed a lot of prior knowledge, and in the process of trying to obtain that knowledge I got even more confused by conflicting answers. I’m sure that all of this would have been covered in a tutorial on node.js or npm, but that’s the whole point- I’m not actually interested in node.js or npm, I just needed a tool for getting something done, in this case configuring search for my static blog.

Think how much worse this is for people who are not competent, or confident! When writing documentation, take a step back and ask yourself if there are ambiguities, or different ways of doing things. If there are, explain that, but then choose one approach and provide complete instructions or link to some that actually work. Check you’ve actually included everything people need to know. Do your instructions only cover half the story? Put that right at the top so you don’t waste their time.

I didn’t intend for this post to become an advert for TheGoodDocs project, but it has ended up like that, so come and join the movement at https://thegooddocsproject.dev/.