General HIG usability guidelines reinterpreted for developer documentation

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
. 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

    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

    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

  • 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

    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.”