Writing software installation guides is a faff. On OU modules, where students provide their own machines, we face a range of issues:
- student provided machines could be any flavour Windows, Mac or Linux machine from the last five (or more) years;
- technical skills and confidence in installing software cannot be assumed (make of that what you will! ;-)
- disk space may be limited (“so am I expected to delete all my photos or buy a new computer?”);
- the hardware configuration may be “overspecced” and cause issues (“I’m trying to run it on my gamer PC with a brand new top of the range GPU card and I’m getting an error…”), although more typically, hardware may be rather dated…
The following is, in part, a caricature of “students” (and probably generalises to “users” in a more general case!) and is not intended to be derogatory in any way…
In many cases, software installation guides, when the installation works and you have an experienced and confident user can be condensed to a single line, such as “download and install X from the official X website” or “run the following command on the command line”. Historically, we might have published an installer, for the dominant Windows platform at least, so that students just had to download and double click the installer, but even that route could cause problems.
This is an example of a “just do this” sort of instruction, and as anyone who has had to provide any sort of tech support ever, just unpacks a long way. (“Just knock me up quick Crème brûlée… The eggs are over there…” Erm…? “Just make a custard…” Erm….? “Just separate the egg yolks…” Erm… ? Later… “Right, just set up a bain-marie…“ Erm…?! “..until it’s just set….” Erm…? Much later… “(Sighs…) Finally, now just caramelise the…” Erm…? Etc.)
More generally, we tend to write quite lengthy and explicit guides for each platform. This can make for long and unwieldy instructions, particularly if you try to embed instruction inline for “predictable” error messages. (With 1k+ students on a module per presentation, even a 1% issue rate is 10 students with problems that need sorting in a module’s online Technical Help forum.)
Another problem is that the longer, and apparently simpler, the instructions, the more likely that students will start to not follow the instructions, or miss a step, or misread on of the instructions, creating an error that may not manifest itself until something doesn’t work several steps down the line.
Which is why we often add further weight to instructions showing screen captures of before, “do this” and after views of each step. For each platform. Which takes time, and raises questions of how you get screenshots for not your platform or not your version of a particular Operating system.
In many cases we also create screencasts, but again these add overhead to production, raise the question of which platform you produce them for, and will cause problems if the screencast vision varies from the actuality of what a particular student sees.
(Do not underestimate: a) how literal folk can be following instructions and how easily they freeze if something they see in guidance is not exactly the same as what they seen their on screen, whilst at the same time b) not exactly following instructions (either by deliberately or in error) and also c) swearing blind they did follow each instruction step when it comes to tech support (even if you can see they didn’t from a screenshot they provided; and in which case they may reply they did the step the first time they tried but not the second because they thought they didn’t need to do it again, or they did do it on a second attempt when they didn’t need to and that’s why it’s throwing an “already exists” error etc.).)
So, a one liner quickstart guide can become pages and pages and pages and pages of linked documents in an online installation guide and that can then go badly for folk who would have been happy with the one liner. Plus the pages and pages and pages of instruction then need testing (and maintaining over the course life, typically 5 years; plus the guide may well be written diring course production a year or more before the first use date by students). And in pages and pages and pages and pages of instruction, errors, or omission or ordering errors or something can slip through. Which causes set up issues in turn.
If we then try to simplify the materials and remove troubleshooting steps out of the install guide, for example, and into a troubleshooting section, that makes life harder for students who encounter “likely” problems that we have anticipated. And so on.
And as to why we don’t just always refer to “official” installation guides: the reason is because they are often based on the “quick start by expert users” principle and often assume a recent and updated platform on which to install the software. And we know from experience that such instructions are in many cases not fit for our purposes.
So… is there a better way? A self-guided (self-guiding?) installation guide, maybe, perhaps built on the idea of “create your own adventure” linked texts? To a certain extent, any HTML base software guide can do this; but often, there is a dominant navigation pane the steers the order in which people navigate a text, when a more non-linear navigation path (by comparison with a the strcuture of an explicit tree based hierarchical menu, for example) may be required.
For years, I’ve liked the idea of TiddlyWiki [repo], a non-linear browser based web notebook that lets you easily transclude content in a dynamically growing linear narrative (for example, a brief mention here: Using WriteToReply to Publish Committee Papers. Is an Active Role for WTR in Meetings Also Possible?). But at last, I’ve finally got round to exploring how it might be useful (or not?!) as the basis of a self-directed software installation guide for our Docker based, locally run, virtual computing enviornments.
Note that the guide is not production ready or currently used by students. It’s a quick proof of concept for how it might work that I knocked up last week using bits of the current softwatre guide and some forum tech support responses.
To try it out, you can currently find it here: https://ouseful-testing.github.io/docker-tiddly-test/
So what is TiddlyWiki? A couple of things. Firstly, it’s novel way of navigating a set of materials within a single tab of a web browser. Each section is defined in its own subpage or section, and is referred to as a tiddler. Clicking a link doesn’t “click you forward” to a new page in the same tab/window or a new tab/window; by default, it open displays the content in a block immediately below the current block.
You can thus use the navigation mechanism to construct a linear narrative (referred to as the story river) dynamically, with the order of chunks in the document determined by the link you clicked in the previous chunk.
If you trace the temporal history of how chunks were inserted, you can also come up with other structures. Because a chunk is inserted immediately below the block that contains the link you clicked, if repeatedly click different links from the same block you get a different ordering of blocks in terms of accession into the document: START, START-BLOCK1, START-BLOCK2-BLOCK1, and so on.
If you don’t like that insertion point, a TiddlyWiki control panel setting lets you choose alternative insertion points:
The current page view can also be modified by closing a tiddler, which removes it from the current page view.
If you click on a link to a tiddler that is already displayed, you are taken to that tiddler (by scrolling the page and putting the tiddler into focus) rather than opening up a duplicate of it.
The Tiddlywiki has several other powerful navigation features. The first of these is the tag based navigation. Tiddlers can be tagged, and clicking on a tag pops up a menu of similarly tagged tiddlers (I haven’t yet figured out if/how to affect their presentation order in the list).
A Tag Manager tool, rasied from the Tools tab gives a summary of what tags have been used, and to what extent. (I need to play with the colours!)
Another form of navigation is based on dynamically created lists of currently open tiddlers, as well as recently opened (and potentially now closed) tiddlers:
By default, browser history is not affected by your navigation through the TiddlyWiki, although another control panel setting does let you add steps to the browser history:
A powerful search tool across tiddlers is also available.
To aid accessibility, a full range of keyboard shortcuts for both viewing, and editing, TiddyWiki, are available.
One feature I haven’t yet made use of is the abilit to transclude one tiddler within another. This allows you to create reusable blocks of content that can be inserted in multiple other tiddlers.
To control the initial view of the TIddyWiki, the first tab of the Control Panel allows you to define the default tiddlers to be opened when the TiddlyWiki is first viewed, and the order they should appear in.
The view of the wiki at https://ouseful-testing.github.io/docker-tiddly-test/ is a standalone HTML document, generated as an export from a hosted TiddlyWiki, that is essentially being used in an offline mode.
The “offline” TiddlyWiki is still editable, but the changes are not preserved when you leave the page (although extensions are available to save a TiddlyWiki in browser storage, I think, so you may be able to update your own copy of an “offline” TiddlyWiki?).
To run the “online” TiddlyWiki, in a fully interactive read/write/save mode, I am using based on instructions I found here: How to use TiddlyWiki as a static website generator in 3 steps:
- install node.js if you don’t already have it installed;
- Run:
npm install -g tiddlywiki - Initialise a new TiddlyWiki:
tiddlywiki installationGuide --init server; this will create a new directory,installationGuide, hosting your wiki content; - Publish the wiki:
tiddlywiki;installationGuide--listen - By default, the wiki should now be available at: http://127.0.0.1:8080/ . When you create and edit tiddlers, change settings, etc., the changes will be saved.
New tiddlers can be created by editing a pre-existing tiddler, creating a link to the new (not yet created) tiddler, and then clicking the link. This will created a not yet created tiddler, or open the current version of it if it does already exist.
You can edit a currently open tiddler by clicking on it’s edit button.
The tiddler editor is a simple text editor that uses it’s own flavour of text markup although a toolbar helps handle the syntax for you.
Image assets are loaded from an image gallery:
The gallery is populated via an import function in the Tools tab.
Looking at the structure of the TiddlyWIki directory, we see that each tiddler is saved to its own (small) .tid file:
$_) and user created tiddlers.The .tid files are simple text files with some metadata at the top and then the tiddler content.
It strikes me that it should be easy enough to generate this files.
Looking at a report such as one of my rally results reports, there are lots of repeaated elements with a simple structure:
That report is generated using knitr from various Rmd templated documents. I wonder if I could knit2tid and then trivially create a TiddlyWiki of rally result tiddlers?
OUseful.Info, the blog... 