full circle magazine #65
37
MY OPINION
some combination of software
that I tended to use that did
something unexpected. He asked
me to grab a log file from Miro,
and send it to him. I did so, and
again he wrote back promptly
pointing out a couple of lines in
the log file, and saying that it
looked like I was missing a critical
package. I checked, and it looked
like this package was on my
system, but I removed it,
reinstalled it, and then Miro
worked properly again. I think this
counts as a very good outcome.
When you create good bug
reports, you help yourself and you
help others. And that is a big part
of what it means to have
Community-Supported Software.
Documentation
In my day job,I am a Project
Manager, and one of the things I
constantly try to get is good
documentation. I hope I have even
produced a little of it myself. But
there is no topic on which I get
more resistance than on creating
good documentation. No one ever
has time to create it, bu t som e h ow
they find the resources to pay the
price when they don’t have it. If
getting good documentation is
hard in the corporate world, how
about in the Free Software world?
It is equally difficult. I can’t tell you
how many times I have tried to
access the Help system for one of
my KDE applications only to get an
error that says there is no Help
material available. You really feel
sometimes like you are being told
“We wrote it, now you figure out
what to do with it.” And part of the
reason is that we don’t always
think about it properly (in my
opinion).
I would start by distinguishing
between two kinds of
documentation: technical, and end-
user. Technical documentatio n , as
the name implies, is the sort of
thing that the developers could
provide if they chose to do so. This
could get to the very deepest level
of code documentation, but even if
it lives at a somewhat higher level,
it is not end-user documentation.
And the question of whether it
even exists remains. Developers
like developing, but they generally
don’t like documenting. And in
Free Software many of these
people are volunteers.
But the topic of end-user
documentation takes us in a
different direction, and one where
people with the right skills can be
very helpful. It can also be a little
frustrating. I recall one experience
I had where I offered to help
create end-user documentation for
an application. When I asked to see
what they had, the response was
“We don’t have anything, that is
what we want you to do.” Now I
like to think I am a good writer, and
I know I have been praised at work
for the documentation I have
written, but any writer needs
something to start with. At work, I
can make the technical people sit
down with me, answer my
questions, and so on. And you
really need something like that to
do good documentation. Good
technical documentation can get
you started, but to do good end-
user documentation you will need
to have some kind of access to the
developers. And if the folks on the
project you want to help don’t
understand this, you need to
explain it to them. They may want
someone to come along and just
magically make something happen
without anyone else on the project
being involved, but that is just not
feasible. Good documentation is a
group effort, really.
In writing for the end-user, you
need to be able to think a little
differently. End-users are, by-and-
large, not technical. There can be
exceptions to this rule, but this is a
good starting place for writing the
most useful documentation. And
the best way to do this is by
thinking of “stories”. The Agile
community tends to do a good job
of this in terms of software
development, but you need to
carry this into documentation as
well. You could write a book on this
topic, and I don’t have that kind of
space here so I will be somewhat
more brief. Stories in this context
means picturing a typical user of
some kind, and imagining how they
might try to use the software. Who
is this person? Be specific – give
this person a name, an age, a sex, a
background. The better you do this
– the better able you will be to get
into this person’s skin and see
things the way they do. Then look
at some questions they might
have.