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

[Jenn Vesperman]

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

On Tue, 2002-10-22 at 21:54, Will Duffay wrote:
> 
> The problem arose when I tried to run a sample php script which 
> I had put in /usr/local/apache/htdocs, as I would do in Windows
> and as is specified in httpd.conf. The URL couldn't be found. 
> Strange I thought. 

Side issue, on most Linux and Unix systems, the httpd.conf (and other
configuration files like that) are likely to be in /etc.
Where was this one?
 
> (As a side issue: from a newbie's point of view, man/info is 
> rather less than helpful (especially when combined with those 
> miracles of intuitive usability vi and emacs: I like the irony 
> of reading the man pages for vi in vi) and it is difficult to 
> find good online support for Linux which doesn't assume that users
> were all born speaking bash script, or whatever. Hopefully one of 
> you can put me back on the path to open-source nirvana, before I 
> turn back completely to the dark side... I really should buy a book 
> about it.)

This is a known issue with open source - and traditionally, with all
software. The problem - as I see it - is that technical writing is seen
as a low status field and as the most 'optional' aspect of writing code.
An awful lot of programmers - particularly juniors - don't see any point
to writing documentation. An awful lot of the rest don't know HOW to
write documentation. And managers often treat documentation as an
afterthought.
How much commercial software comes with no useful manual?

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.

And trying to decide whether to program (high status, high visibility,
and dammit there's an awful lot of usability programming that NEEDS to
be done), or document (low status, low visibility, but thank $DEITY for
the Linux Documentation Project because without that much of the work
would be ignored anyway).

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

I've been doing Unix/Linux stuff for more than ten years now. Man pages
are plain english to me - sometimes poorly written english that doesn't
have the information I need, but they're readable.
I know intellectually that new users find them confusing. But for me to
write something 'better' involves guessing. Trying to blindly grope for
what's not understandable.

Aiming your writing at the right audience when you're NOT that audience
is a skill and an art.


Anyway, all of this is a way of saying: YES! WE NEED WRITERS! Write
something! Please!

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

You're welcome to use my Newcomer's Guides (available at
http://www.cyber.com.au/users/jenn/) as a source of ideas for approach,
outlines, or whatever.

You're welcome to ask for help, and we'll do what we can to provide it.

But those of us to whom bash and man are second nature are NOT the best
people to write newcomers' guides. And newcomers seem to think 'but I
can't do that, I don't know anything!' And once newcomers -learn- it,
they lose that essential perspective that would make a truly useful
newbie's guide. Argh.




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/