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

[Jenn Vesperman]

On Wed, 2002-10-23 at 06:25, Akkana wrote:
> 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?

Y'know, that's a point. I guess it is.

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

Agreed.

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

Especially since - at least when I went through Uni - many of my peers
perceived themselves as bad at writing. At least writing English.

> That's not aimed at Jenn -- she already does this!

Thank you. 

I've decided to take on puzzling out Kerberos and writing Kerberos
documents as my next project (and selling them as O'Reilly Network
articles, where they'll be available to read for free & reasonably easy
to find).

Admittedly, Kerberos isn't a thing most newcomers will use - but it's
still a poorly-documented tool. Poorly-documented as in 'most of the
documentation assumes you understand Kerberos already'.

But to misquote Alice - I'm already writing as fast as I can.

> 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?

And yes, you -can-. What you don't yet know, you can ask about. Most
developers are happy to have someone else writing the documentation, and
will gladly answer questions.

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

And send the URL to the Linux Documentation Project, and ask if they
would like to archive it. If they would, they -will- ask you to get it
in Docbook format, and may ask you to make other changes. But there are
people who can help with those, either here or by telling the LDP that
you don't know how to DocBook it.

(for that matter, DocBook is one thing that, last I looked, could use
more newcomer-friendly documentation.)

> > (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!

Absolutely.



Jenn V.
-- 
    "Do you ever wonder if there's a whole section of geek culture 
        	you miss out on by being a geek?" - Dancer.

jenn at anthill.echidna.id.au     http://anthill.echidna.id.au/~jenn/