Re: Software quality and documentation, was: Core KDE member about HIG^W female contributors
On Tue, 17 May 2005 19:00:13 +0200, Peter Samuelson <firstname.lastname@example.org> wrote:
I'm not -- and I'm not talking about exchanging one hierarchy (coders
above all others) with another (documentation people above all others) but
exchanging hierarchy with equal partnership.
The people who write the best code I know write documentation
alongside or even before coding: The code has to follow
documentation, otherwise it's a bug :)
So, back in context of the current discussion ... we're not talking
about coders who write documentation, we're talking about documenters
and coders being different people. Thus you're really talking about
shifting the design of the program from the coders to the documenters.
I'm very much aware of that you will always find people who just do as
some $big_boss says, e.g. documentation people who will simply describe
what they get. You may continue to look at these people as "subordinate",
and the result you will get is the usual "'File | new' opens a new file."
type of documentation which we -- unfortunately -- find everywhere and
which is almost as good as no documentation at all.
I'm not talking about those documentation people who are fine with this.
I'm talking about people who often know a lot more about software
usability, user interfaces and documentation than the average coder, but
can't or won't write code. Some of them because they don't have enough
practice (many of them will be able to read well-designed, well-commented
code but won't touch the code themselves), some because they don't like
coding, some of them because understanding the code in all small details
would take too much time... (other reasons I leave to your imagination).
I agree: people with these qualifications are as rare as brilliant coders
but they exist, and I bet you will find as many of them as you find
brilliant coders. At present, Open Source projects usually use the
qualification of those brilliant coders but _not_ the qualification of
those people. Instead they scare them away simply because of this
And I tell you why (let's take an UI example because this is more
obvious): Many coders aren't good at user interface design -- which often
has to do with code- instead of user-centric thinking. You wrote this
code, you can use it easily since you know how the code works.
Unfortunately, none of your users receives a brain-dump of your brain
together with the software, so things that might seem obvious to you
(because you wrote the code) but definitely not to your users. As long as
you don't want other people to use your program, that's just fine. But
then you don't need documentation people at all :)
Right, the documentation person usually is someone who uses your code
extensely -- simply because in order to write good documentation you have
to grok the program in every detail. Now $documentation_person finds, say,
a dialog which he or she does not understand at first. Chances are good
that other users won't understand it either. When $documentation_person
finally understood it, he or she often has an idea how to solve this
problem. Sometimes it's just wording. To solve the problem you need to
edit code (describing the problem in documentation when you know how to
fix it is only a bad, bad work-around.)
But: $documentation_person needs to beg, and beg, and beg $coder to fix
this problem. Often $coder won't see the problem (remember: for him it's
not a problem since he wrote the code) and not fix it. Or because this is
"only" a ui-problem it gets a low priority on the todo list (this other
coool feature always has priority).
Do you think $documentation_person will try a second time? I'm sorry, I
Do you think you will get quality documentation this way? I don't. If you
don't recognise your documentation person, your translater, whatsover as
equal partners, also when it comes to design issues, you won't get the
best quality they have to offer. Try to discuss design with them, and if
you're lucky, you might find out that you have extremely qualified people
in your team. Maybe you need to use a different language to describe the
issue, need to explain technical terms, and maybe you need to encourage
them (since many of them are used to that subordination where they are
recognised as cheap helpers only). Some of them are quite capable of using
version control and stuff and could fix a wording problem themselves,
perhaps with a little help of you.
So why don't $coders use this power? Often because they don't see the
problem, and even more often because to fix this stuff
$documentation_person comes up with is boring. Right. But remember you
want this documentation person to do stuff (writing documentation) that
you consider boring.
So please do everything that he or she has fun as well, and not just you.
It's definitely not fullfilling to ask for an CVS account and not get it
because "you're not a coder". It's definitely not fun to come up with good
suggestions and see them being ignored. It's definitely not fun to see how
this coder person does fun stuff, and that's why give your bug-reports low
Do you see what I mean?