Re: Software quality and documentation, was: Core KDE member about HIG^W female contributors
Patricia Jung wrote:
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.
Well, it's also because the first priority is usually "get something
done", not "make it easy" -- better to succeed at the former and fail at
the latter than vice-versa, after all.
You wrote
this code, you can use it easily since you know how the code works.
That's often not true, anyway, IME. :)
Right, the documentation person usually is someone who uses your code
extensely --
And hence the documentation person (how about we use the crypto
tradition of giving people mnemonic names? Carol the coder and Dave the
documenter, say), Dave, only arrives on the scene after Carol's invested
a fair chunk of time in developing the application already. That's an
immediate "subordinate" relationship -- just as it would be if the new
arrival had been Cindy the coder, or Ursula the UI-specialist.
Now $documentation_person
finds, say, a dialog which he or she does not understand at first.
"Hey, I found a grammatical error! Here's a patch!" is a long way from
an equal partnership with "I thought up this program and spent the last
n months building it from nothing and working on it and helping people
use it".
I'd usually expect someone with a comment like that to disappear and
make similar comments on other completely different things ("Hey, green
and red are really bad contrasts for colour blind people!") than to help
me design version 2.0 of something from a, say, use-centric perspective
instead of an implementation-centric one.
I just don't see how you get from one to the other.
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,
But who gets a translator or a documentor of their own? The
interfaces(5) manpage was written by Joey Hess who's got plenty of other
things to do anyway; Matt Kraai wrote debootstrap's man page, and
there've been patches from various folks, but JHM's the only one who's
really stuck around; and the translations for my packages have always be
done by random folks who translate lots of Debian stuff.
I may just be jealous :)
So please do everything that he or she has fun as well, and not just
you.
(If someone's feeling particularly inspired or bored or some combination
thereof, and wants to fork a thread on how much debootstrap's UI sucks
monkey butt, that could be interesting -- it's due for a complete
do-over anyway)
Cheers,
aj
Reply to: