[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

On Tue, 17 May 2005 19:00:13 +0200, Peter Samuelson <peter@p12n.org> wrote:
[Patricia Jung]
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 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.

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

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 don't.

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

Do you see what I mean?


Reply to: