The secret of good documentation is empathy

26 June 2013

Writing documentation is hard, but that’s no reason to skimp on it if you want to run a successful software project. It’s certainly one of my least favourite activities, and usually one I put off right until the last minute, but the existence of good documentation is often the deciding factor whenever I’m assessing whether to use some software.

I have become accustomed to most documentation being pretty crappy though - so much so, that sometimes I forget to even look for it. I’ve been learning the JavaScript library Knockout this week, and I’d looked a few things up on Stack Overflow before realising that Knockout’s own documentation is excellent.

What I like about it is:

  • it's written to help me out, as a new user who knows nothing about Knockout
  • it explains why I would want to use it in the first place
  • it guides me through the key concepts, with examples
  • it doesn't shy away from the "advanced" stuff, but it flags it up appropriately - so if you're more of a JavaScript novice, you know which parts you can safely skip, but if you want to know more detail about what it's doing, all the info you need is there
  • there is a clear progression through the documentation - pages are relatively free of links, which keeps you on the right path, but if you want to jump in and look something up it's easy to do so

It’s just the right amount of detail - not too little, not too much, and you can read the whole thing in quite a short amount of time and feel like you have a good understanding of what Knockout is and how to use it.

While I think of it, the documentation for Bootstrap is another example which manages to get this kind of digestible tutorial-but-also-reference thing right.

As much as I love PhoneGap, I wish their documentation was as good as this. Frequently, it’s not kept up to date, which can lead to a lot of hair tearing even when trying to follow something as simple as the guides for setting up your first project. How many users have been put off using PhoneGap at all because of this?

I think all that’s needed is a little empathy. Remember that a new user doesn’t know anything about the software - and their first question is “why the hell should I bother using this in the first place?”

Answer that, and then think about what they’ll need to know next. Simple stuff really. But apparently, easy to forget. Why?

Nobody will tell you how badly you’re screwing up the experience of the first time user.

New users won’t give you feedback. They’ll move on elsewhere - maybe to some competing software, or maybe they’ll just give up on the whole idea of what they were trying to do anyway. They’ll think it’s their fault. They must have set up their computer wrong, or they’re too stupid to understand this, or this software isn’t really for them anyway.

I did experience some “road bumps” with Knockout even though its documentation is great. Fortunately, these only occurred after I was quite far through reading it, so I persisted instead of giving up. Did I just miss something by skimming over it? Maybe - after all, most people skim when reading on the internet, and I’m no exception. Maybe I’d just failed to grasp something which was never explicitly stated, and that functionality could have worked in a number of ways.

Having solved my issue, nobody is ever going to get to hear about what it was, or how I solved it. Other users may have the same problem, and will have to figure it out themselves too. The maintainer of the documentation will never know - there is no channel for me to say “I didn’t understand A, until I realised B”. There will be no bug report for an issue which may be unique to me and my brain.

IFComp 2013 announced

25 June 2013

The IFComp 2013 has been officially announced!

This is the biggest text adventure competition there is - now in its 18th year. Entries can be written for any interactive fiction platform, and it usually gets some good coverage out there in the wider world. Many authors wait for the competition to release the game that they’ve been working on all year.

This year, I’m planning to be one of those authors myself, with my first work of interactive fiction - eeek!

There are prizes to be won too. As it’s only just been announced, no prizes have been donated yet, but you can get an idea of the kind of thing by looking at last year’s prizes.

If you’re planning to enter, take a good look through the rules. Note that all entries must be previously unreleased - this means if you’re working on a game now that you want to enter into the competition, make sure you don’t release the game publicly beforehand. This doesn’t stop you from having a few beta testers though - and in fact, getting your game tested by a few people is something I’d strongly encourage!

You have until 1 September to declare your intent to enter and until 28 September to upload your game. Games are made available a couple of days later, and the results are out on 15 November.

Good luck everybody!

Preventing your software from descending into an abyss of complexity

25 June 2013

Nice article by Kris Gale on the hidden costs of complexity in software:

Among the most dangerously unconsidered costs is what I've been calling complexity cost. Complexity cost is the debt you accrue by complicating features or technology in order to solve problems. An application that does twenty things is more difficult to refactor than an application that does one thing, so changes to its code will take longer.

I used to work on a huge financial software product, written in VB6. Legend had it that this was the largest VB6 program ever built - hundreds of different components. And it was painfully slow to work on. The whole application desperately needed refactoring, yet despite there being a team of 20 developers working on it, development had basically completely ground to a halt. We were all busy, of course - plenty of bug fixes and minor feature requests - but it never felt that the application was noticeably getting better.

There had been an attempt to move the application into the world of .NET, but all that had achieved was creating a hybrid VB6 and C# application that added yet more layers of code. Nothing was ever removed, or stripped back, or simplified - just more and more code added to the pile.

It meant that it took a long time to add any new functionality, as you had to dig through all of the layers, and inevitably changing anything would cause something to break, often in a subtle way in a completely different part of the application.

I used to enjoy coming home from work and hacking on Quest for a few hours, because it felt like I had suddenly become 1000x more productive, and could add new features and fix bugs almost scarily quickly.

Now that Quest is (for the moment) my full-time job, and with its codebase having grown quite considerably over the years, I have to be careful not to bring the same problems upon myself. All software tends to stagnate over time - I’m reasonably happy with how my own architecture is holding up, but even then I often find I’m slowed down by having to ensure that it always remains compatible with games created for older versions, and that any changes I make to how it works apply across both the desktop and web editions.

In some ways, it would be nice to strip things back a bit - perhaps making it a web-only product, instead of there being a Windows desktop version too. The existence of the desktop version seems a bit “legacy” now, but there still a genuine need for it - schools don’t yet always have reliable or fast internet connections for example.

The challenge, then, is to ensure that any complexity that exists is there for a good reason, and to keep an eye open for where things can be simplified. It’s very easy to ask “how can this software do more?” - perhaps we should also sometimes ask “how can this software do less?”

Try throwing away some stuff

24 June 2013

Alex Kristofcak has an interesting idea:

To fight the plague of accumulating crap I came up with a business idea: after you sign up, you get an empty box in the mail with a paid return label every month. You fill it up with stuff you don’t need and send it back. You then get a $10 check.

We’ve been decluttering our house for the past few months. We’ve got rid of a whole load books and useless old gadgets. Novelty lamps. A blender. Vases. Cameras. Suitcases we never used. We’ve got rid of furniture.

We’ve gone through our cupboards. I had old computers from the 1980s in there that I was never realistically going to get out again. There were old DVD players and VHS recorders.

Every little thing. Even a teapot we didn’t need. We already had another one - who needs two teapots?

Rachel even got rid of most of her CD collection. I’m still too sentimental to get rid of mine - even though I rarely listen to CDs these days. Maybe one day.

The extra space has meant we can get by living in our fairly small house for a long time. That’s a huge money saving. It’s also good for the mind - freeing ourselves of the guilt of not using all our stuff is hugely liberating. We can get on living our lives as they are, without sharing our home with past versions of ourselves, or indeed, the fantasy versions of ourselves who in our imaginations would one day actually use all these things.

Sort of new blog, or possibly doomed short-lived experiment

21 June 2013

I’ve given my personal blog a shiny new theme and I’ve started posting some more stuff on it, as you may have seen.

I already have another blog - the Text Adventures blog - but I often have thoughts which are nothing to do with that, which I can’t quite squeeze pithily into 140 characters, so I’m going to try putting some of them here, instead of doing my best to ignore them.

I’ll try not to spend too long writing them though. In the past I’ve spent entire days on epic blog posts, which nobody was particularly interested in. Also, I’ve got work to do.

So, hello.

All Posts