[Techtalk] Re: [Grrltalk] Documentation (was: Mandrake/Linux newbie deep in confusion about apache/advx)

[Akkana]

Jenn Vesperman writes:
> (Moved to grrltalk, as I want to discuss the documentation aspect - I
> know almost nothing about PHP or Mandrake.)

Is technical documentation not an appropriate subject for techtalk?

> The problem - as I see it - is that technical writing is seen
> as a low status field 

You've probably seen more than I have, but at least at most companies
where I've worked, the tech writers are usually well respected.

> and as the most 'optional' aspect of writing code.
> An awful lot of programmers - particularly juniors - don't see any point
> to writing documentation. 

That's true, alas, and I think Meredydd hit the nail on the head as
to why: they're not used to having it available for them, so they don't
think of it as something necessary and important.  Also, they're busy
writing code, without which there'd be nothing to document ...

> An awful lot of the rest don't know HOW to write documentation. 

I'd like to add something to this: when developers DO try to write
documentation, they often get criticised for it: "That wasn't easy to
read!"  "I didn't understand it!"  "How dare you use big words?"
That doesn't provide much positive reinforcement for continuing to
write documentation (and getting better at it).

Why is it that open source projects get far more contributions in
C than they do in English?  Surely a lot more of the people who complain
about the project speak English than speak C?  Yet when whining about
a project, very few people ever consider writing documentation as
a contribution *they* can make to the project.

So, while I agree that developers could write more documentation,
I don't understand why documentation writing has to be entirely up
to developers.

> And managers often treat documentation as an afterthought.

This is also true, and a problem.

> In the open source world, the man pages and info pages are usually
> written by the programmers, once they've done the 'important', 'fun' or
> 'interesting' bit of writing the code.
> 
> Those of us (like me) who consider documentation important are left
> ranting, screaming, and trying to teach.

Instead of ranting and screaming, how about doing some writing, and
send it in as a contribution?

That's not aimed at Jenn -- she already does this!  But any of you who
found yourself nodding at what she wrote, ask yourself this: how many
pages of documentation have I sent recently to open source projects?
Is there any open source program which I know how to use, which needs
better documentation than it has?  Could I write that documentation?

> Then there's the other big problem. Finding out what needs to be
> documented most urgently.

That's easy!  If you learn to use something, and it was hard to learn,
and you couldn't find any documentation, then once you've learned it,
document what you learned!  Write it up as a page on your own site,
then contact the project and see if they'd be willing to put your
page (or a modified version of it) on their official site as part
of the project.

> (gets down on her knees)
> 
> I'm begging you. Write a beginner's guide. Ask us for information, ask
> us for pointers, but _write it_. I'm certain the LDP would be happy to
> host it.

Yes!  If you find the existing documentation confusing, then that means
you've already found a place where you can contribute!  Note what parts
are confusing, and write something better.  And submit it, so it will
benefit other people too.  That's how open source works!

	...Akkana