As promised before (although later than I promised), here is my theory
on how some of the
general HIG usability principles can be interpreted in such a way that
they provide great guidelines for how to write documentation for
beginners. Note that this may not make sense without reading my
Atrocities of
Gnome Developer Documentation blog entry or my other follow up entries.
-
Don’t limit your user base
Applied to user interfaces, at the most basic level, this means
things like not requiring first time linux users to compile
their own kernel in order to try linux out. At a higher level,
it means things like taking care of a11y and i18n, among other
things.Applied to documentation and taking the more basic level
approach, it means not requiring beginners to learn autotools,
compiling from CVS, or some other similar expert project. One
of the higher level meanings (though I don’t believe this is
actually a good idea for most documentation, at least not in a
single work) could be to include other language bindings so that
you don’t lose all the programmers who don’t know C. -
Keep it simple and pretty
For user interfaces, this is just a result of the fact that
feature-ridden applications confuse beginners, slow them way
down, and turn them away.For documentation, the problem is the
i-must-be-comprehensive-syndrome. Beginners usually just want
the basics of a given library or tool, not every detail about
how it can be used. -
Use familiar terminology
For user interfaces, this can mean things like including the job
of an application in the menu entry instead of just using the
application name (e.g. “Mozilla Web Browser” instead of
“Mozilla”)For developer documentation, this can mean things like
describing libraries according to what they are used for, not by
the technologies they employ. (e.g. Describe libxml as “These
libraries provide fast parsing of XML (Extensible Markup
Language) files. XML is a file format which is often used for
configuration files, documentation, and many other things.”
instead of “Powerfull and feature complete XML handling
library.”) -
Let users know what’s going on
For a user interface, this means things like providing an audio
beep, error messages, or progress indicators.For documentation, this could mean giving budding developers a
high-level overview of what they will need to learn. -
Put the user in control
I also like to think in terms of “reward the user”, which I
think is closely related. From the HIG it means things like
avoiding modes so that users can switch between applications and
windows at any time.Developers reading documentation aren’t in control–they’re
trying to gain control. Developers who are working on a project
are in control. Thus, it’s important to give developers small
projects to work on early, and to get to simple yet useful
examples as quickly as possible. -
Make your application consistent
For user interfaces, making your application behave similarly to
other applications enables users to apply their existing
knowledge of their computing environment and other applications
to understanding a new application. Making things inconsistent
means the user runs into surprises when using new applications
that slow them down or make them lose a sense of trust in the
environment.For documentation, people try to apply their knowledge from
reading books they bought at the store to Gnome documentation.
Most developer documentation starts with the basics, however
Gnome documentation starts with the nitty gritty. Thus, new
developers feel “Wow, the basics are this hard? There’s no way
I’ll be able to master even the intermediate stuff, let alone
the advanced.”