Abstract Models Answer Questions

I've just installed MS Word'97 and the help stuff is driving me nuts. For example, I wanted to understand about languages, just how a document got a language attribute, how parts of it might be given other languages etc. I have to deduce this (simple, in this case) model from several "to achieve this, do this" pieces. Aaargh.

I also want to know about styles, but I've given up on that one. What can override what? What does the indent button do? Enough! Time for bed.

Of course one of the reasons the model isn't exposed is that it's such a muddle.

BruceAnderson 14vi98

It would be nice to have a pattern language for user manuals. Is there one?

A manual has to answer several kinds of questions:

It needs a feature list, probably. Actually you can get this by looking at the running program's menus and toolbars.
It needs to tell you how to do common tasks. You can work it out from the feature list, but users apparently don't want to do this.
It needs to convey the gestalt, the overall architecture, the metaphors, the user model. It should provide a framework off which the details can hang.

It sounds like Word got as far as the middle stage.

Similar issues arise with programmer documentation. Can the bare source code give you more than a feature list? One difference is that programmers are paid to figure it out, by looking around. Users just want to write their letters. -- DaveHarris

For programs I don't really want to understand (and Word is one of them), I've actually gotten rather fond of the "how do I ..." form of documentation. However, it really has to work: that is, the index has to offer me the thing I want in a try or two. And it has to be very complete. I'm a little worried about this change in my preferences, as I used to want to understand everything. Maybe using Smalltalk has something to do with it. -- RonJeffries

I have found something similar. The programs I have been involved in have begun to grow faster than my ability to understand them. I now settle for understanding little pieces on an as needed basis (and question how "fully" I really understood programs in my younger days). I must admit, however, that Word often seems far beyond any form of understanding and until the little paper clip can answer the question, "What the hell did you just do to my document?" I am stuck randomly deleting and reinserting things until the editor creates (or recreates) what I want. -- WayneMack

I find that this applies to code (class libraries in particular) as well as applications. For instance, learning how to use JAI, the java imaging toolkit, was a real slog, as there was no document saying "the world contains RenderedImages? and PlanarImages?, and these are related as follows". I had to surf the javadoc to try and identify the focal classes. The tutorial helped, i admit, but the documentation was crying out for an architectural overview. I suspect the reason that there wasn't one is that the architecture is a complete nightmare! 8P

-- TomAnderson

One of the ways abstractions answer questions is in the way in which the abstraction is constructed. If it is anticipatory, it has a greater likelihood of answering a question not yet ask. In other words the construction anticipates utilizations.

Amen, brothers. If you really want to ask some questions and get some answers, try building a model of your Help system in Alloy. Alloy is a lightweight modelling language designed by DanielJackson for the purpose of exploring high risk parts of systems without having to model (or build) the entire system. You use Alloy to describe the static structures of your system and to declaratively define its operations in first order relational calculus. You assert properties of the system and let a checker program search for counterexamples. When an assertion fails, the example that broke it is presented, so you can pretty easily figure out what went wrong. I'm studying the manual now, having learned Nitpick a few years ago and had a ball with that. If you decide to try this, you'll find a mail list on Yahoo called alloy-discuss where to share your triumphs and troubles. -- WaldenMathews

For Alloy see http://alloy.mit.edu/