Troubleshooting as a Choose Your Own Adventure

READ MAP

We have a lot of documentation and help in the Ubuntu project, and much of it is quite hostile to new users. We have IRC channels, mailing lists, dense & out of date wiki pages, lengthy and hard to consume forum posts & lengthy out of date tutorial videos. We also have some more modern tools such as AskUbuntu and Discourse.

Most are good for asking one specific question, but most aren't well suited to guiding a user through a specific problem diagnosis. If you know what questions to ask, then a search engine might find part of the problem, or hopefully part of the solution.

However one aspect we don't cover very well is guided self-support. This is very apparent in distribution upgrades. People often give up completely when an upgrade breaks down, rather than work through the problem as they would with anything else. There can be many reasons for this of course, but from what I've seen in the community, fixing a broken upgraded system is hard, and made harder when you only have a black screen, or tty to work with when you're not an expert.

GET ROPE AND SWORD

I'm thinking very specifically about a target audience of non-technical users. Someone who uses Ubuntu but wants to feel empowered to fix a problem themselves, and not have to call their wife or daughter or other 'expert' to fix it. I want someone to find a guide which gets them out of the upgrade issue. Obviously I'd like us to fix the problem which cause the issues, but I want to start here, because frankly it's easier for me.

WAIT

While I can hear some of my co-workers shouting "But popey, Snappy Core fixes the issue of broken updates!", no it doesn't, not today, and not while there are people running the traditional Debian based desktop - which I suspect will be for a good few years yet.

WAIT

I can also hear those of you saying "I never do upgrades, I always clean install", and I'm happy for you, but we have an upgrade system, people should be confident that it works, and when it doesn't it should be fixable without going nuclear. Just the same as "Buy a new TV" isn't usually the solution to "My TV Remote stopped working".

EAT LUNCH

In my mind a user might be more inclined to fix their system if there's an easy to use 'expert system' which they can walk through to get them working again. I wondered about this some time back and considered the idea of a Choose Your Own Adventure style of troubleshooting issues, rather than just punting people to IRC when their system breaks. We have been helping people with broken upgrades for years, surely we can amass the technical knowledge into a self-service system to help future users.

One assumption I am making with this is that the person going through this is able to access the Internet (and thus this guide) via another machine or their phone. This seems semi-reasonable as we often get people in IRC or on other support resources asking for help with a broken upgrade. So the guide should work well on any browser and ideally on mobile too.

There are of course unfortunate people for which they have only one computer and no smartphone so have no way to access this resource easily. This system doesn't cater for them well.

GET BARREL

I made a little prototype using Twine which is an "an open-source tool for telling interactive, nonlinear stories." - typically text adventure or "Interactive Fiction" games, but can be used for other things too. I chose Twine because it's open source, easy to use, cross platform and simple. You can even create Twine 'stories' directly in your browser. Neat!

The output generated by Twine is HTML and can be customised and styled with a stylesheet. I did one simple bit of styling in that I used the Ubuntu font :).

THROW BARREL THROUGH TRAP DOOR

Here's what the map of the 'world' looks like inside Twine (after I carefully moved the blocks around so none criss-cross):-

Twine Screenshot

Editing the pages within the 'story' is super easy, linking to other pages is as simple as typing the name of a new page in square brackets:-

Editing a page

You can try out the very early prototype I made at http://popey.com/~alan/twines/UbuntuUpgrades.html. Obviously this isn't finished, won't actually help anyone fix their system, and is hosted somewhere obscure, all "TODO" items.

OPEN CURTAIN

There's a few known issues with the above prototype twine:-

  • Browser back button exits the story, it should go back a step
  • Twine back button is hard to see, some CSS will fix that
  • Many of the pages are quite wordy, or technical, probably could be simplified

SAY TO BARD "SHOOT THE DRAGON"

I wanted to share what I'd done to see if it seemed like a good idea, and whether people might be interested in helping create and curate content for it. The idea is to make a prototype and get some content rather than make the thing look especially pretty right now. The way I see it there's some important steps to do:-

  • Confirm this isn't a stupid idea (this blog post)
  • Figure out the best way to distribute this and make it accessible
  • Find people interested in helping
  • Identify a bunch of specific breakages that happen in Ubuntu upgrades
  • Craft diagnostic steps to identify one breakage scenario from another
  • Come up with robust solutions for each scenario
  • Test the scenarios
  • Publish and publicise the work

Things I haven't yet considered, but probably should:-

  • Translations
  • Accessibility
  • Co-ordinating work
  • How far back I'll roll my eyes at people telling me rolling distributions are better

PUT TREASURE IN CHEST

Comments, suggestions or flames are welcome here or in my inbox.

Comments

Comments powered by Disqus