A usable user manual

This week has been spent working on a new user manual for the Bedrock computer system, which turned out to be a more challenging task than I’d first hoped.

Writing a manual

Back when I first started developing Bedrock, when the whole system was in a constant state of flux, the only user manual that existed was the specification. It would’ve been way too hard to keep a manual synced up with all of the changes that were happening at the time, and everything was right there in the specification anyway.

After a while though the changes slowed down, and it became clear that I should start working on a user manual to compliment the specification. The specification was written in a bottom-up manner, which was great if you needed to know the exact behaviour and limitations of a specific component, but it left the intended uses and big-picture interactions between components mostly down to implication.

The user manual, however, needed to be written in a top-down manner, focusing on the kinds of tasks that people wanted to perform with Bedrock. Where the specification might describe the pixel and colour formats supported by the screen device, the manual would instead explain how to draw a line or a picture. It would help people to do real work, with as little friction as possible.

A structured approach

This first manual is still in use, you can see it if you go to the Bedrock project page. It’s fine, all things considered, and it’s a lot better than nothing, but it’s trying to do too much at once and suffering for it.

I wasn’t sure how I should structure the manual when I first went about writing it, so I started with a copy of the specification and took to it with a scalpel and pen. It’s not hard to see this heritage glinting through as you read it; the structure has remained intact, to the degree that I was able to stitch the two documents together with hyperlinks for easy cross-referencing.

It was only after I wrote that first manual that I got around to studying a proper book on documentation — How to Write a Usable User Manual by Edmond H. Weiss — which gave me a lens through which to critique what I’d written. I first stumbled across this book at the Vic uni library in Wellington, and was later also able to find a copy on archive.org.

The book presents a taxonomy of documentation, where any piece of documentation can be categorised as either a reference, an instruction manual, a tutorial, or a demonstration (we’d call this an example nowadays, but demonstration is perhaps a better term).

In this light, the current Bedrock manual is quite a mess: it’s trying simultaneously to be a reference manual (full of exhaustive tables), an instruction manual (with task-oriented descriptions), a tutorial (trying to help the absolute beginner), an a demonstration (with an example for every feature). The manual ended up occupying an uncomfortable area between all four functions, while not doing a very good job at any of them.

Plan to throw one away

This week I started work on the second revision of the user manual. I’d just recently finished writing the new user manual for Torque, so I figured it couldn’t be too hard to write a new one for Bedrock right after. What I hadn’t considered was that Torque and Bedrock are very different projects, despite superficial similarities.

With Torque, the documentation needs only to explain a handful of language features, and how they can be used together to generate different types of data. There’s no way to demonstrate how to actually write useful programs in Torque, because the meaning of the assembled code differs wildly depending on the target processor. With Bedrock however, the assembled code is only really an implementation detail; what people care about is the behaviour of the program when run.

Where the Torque manual describes how to encode characters as bytes, the Bedrock manual needs to explain how to actually use strings, how to draw them or print them or check their length. We can’t just document the assembler and call it a day.

False starts

So, what happened was that I tore into the assembler and instruction set sections of the manual with great gusto, but once I reached the device interface sections I found myself stumbling, unsure how to proceed.

The first version of the manual made heavy use of code examples to demonstrate how the different devices can be used, with each example being a short, self-contained program that can be executed right there on the page. The issue with these examples though was that they have to be short, readable, informative, useful, and self-contained, and I was coming to realise that these goals were all at odds with one another.

For a program to be self-contained, it needs to include the definition of every macro and function used. For a program to be readable, it needs to give short names to common patterns with macros. For a program to be useful, it needs to use functions that aren’t strictly related to the feature being demonstrated. All of these requirements will explode the length of a program, increasing complexity without really helping readability.

I’m only just reaching this conclusion now that I’ve typed all of this out, but I think that the best approach for the new manual will be to restrict the scope to cover just the Bedrock system itself, rather than trying to demonstrate all of the possible use cases for each feature. Instead of showing how to draw a rotating cube, for example, the documentation should restrict itself to explaining basic tasks like drawing a line and changing the colour palette. A separate piece of documentation could be written in the future to show-case some advanced example programs, like one of those ‘Learn BASIC’ books from way back when.

Next steps

I’ll keep working away on this as I get spare moments over the coming month, and I’ll polish up the sections that I have finished for people to see. This project is high on my priorities list, a more usable user manual will help to legitimise Bedrock as a viable platform for software development.

Thanks

Thanks again to everyone for supporting my work, I hope you all have a great week!