[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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)


Reply to: