Date: Mon, 14 May 2001 10:36:23 +1000 From: Sue Blake <sue@welearn.com.au> To: Doug Young <dougy@gargoyle.apana.org.au> Cc: Rahul Siddharthan <rsidd@physics.iisc.ernet.in>, Kathy Quinlan <katinka@magestower.com>, N6REJ <n6rej@tcsn.net>, freebsd-doc@FreeBSD.ORG Subject: Re: I'm leaving Message-ID: <20010514103623.B68348@welearn.com.au> In-Reply-To: <024b01c0dc05$b1314fc0$0300a8c0@oracle>; from dougy@gargoyle.apana.org.au on Mon, May 14, 2001 at 09:37:35AM %2B1000 References: <002b01c0db54$e0febaa0$5599ca3f@disappointment> <20010513171444.E26123@welearn.com.au> <00f401c0db7e$ff3ca2a0$fe00a8c0@kat.lan> <20010513122623.I97034@lpt.ens.fr> <20010514084709.A68348@welearn.com.au> <024b01c0dc05$b1314fc0$0300a8c0@oracle>
next in thread | previous in thread | raw e-mail | index | archive | help
[Moved, it's a -doc issue now (was advocacy and newbies)]
On Mon, May 14, 2001 at 09:37:35AM +1000, Doug Young wrote:
> > And that is exactly the problem faced by many newbies: not knowing
> > where to look, nor realising they're there when they've found it.
> They
> > can't tell because there are concepts that they don't have, and when
> > they look at the documentation they might find vaguely familiar
> words
> > which are not used in every day speech and which have a particular
> > meaning to people with a formal computer education.
> >
> :) ..... its called "martian" .... or maybe I'm confused & its really
> "venusian" !!!
I thought it was Klingon :-) Whatever it is, your MUA's line-wrapper
seems to have come from the same place :-) I'll rewrap for you.
> There is a limit to how much martian / venusian most of us can absorb
> in a hurry. For many people its very limited, so since the official
> folk didn't learn to speak the same language the majority of regular
> folk do it appears that meaningful docs can only be written by a team
> comprising someone with a reasonable grasp of english (or whatever
> language), an expert or two in a consultancy role, plus an
> interpreter who may not be an expert developer but speaks both the
> developer language & english (or whatever)
The problem we have is that the people with the skills to execute
these good ideas, either don't contribute them to our docs (and
we're left with a volunteer staff of hard working Klingons trying
their very best), OR, they go off and do their own thing somewhere
else, which is great to have but fails to enrich the FreeBSD docs
in any way.
Like so many things round here, we have lots of people ready
to jump up with good ideas, even more people weeing themselves
with excitement at the chance to code the infrastructure, but hardly
a soul to do the actual work. This applies to FreeBSD doc ideas
as much as it does to support ideas. "If you build it they will come"
is a naive view does not work for support/docs, but it has been a
popular pipe dream for the several years that I've been watching.
Better docs/support requires supply of prose, not code.
The first thing we need is people, working within the community,
to do the stuff. You can sketch out a few docs and send them to
freebsd-doc. I find SGML intimidating, but plain text is fine.
If it's valid and useful, after feedback and editing and completion
someone will step forward and mark it up and commit it for you.
Anyone who doesn't want a precious word of their prose altered
will have to do it some other way, of course. And there are other
reasons why some people keep their docs sepaparte from the FreeBSD docs.
But in general, we need people contributing to docs if there is going
to ever be any improvement. And we need bums on seats and text on file,
way way way before we need more should-be and should-be-nots and code.
> > With these, once you've seen them in a unix context they're
> > obvious, but they don't have instant meaning that leaps out for a
> > beginner.
> >
> So why the commandment "Thou shalt never use visual representations"
> (aka screenshots) ?? Hey maybe the docs folk are all visually
> impaired & use one of those screenreader apps like "Jaws". Might
> explain why all "official" docs muddle through with largely
> unintelligible text rather than the 'picture tells a thousand words"
> approach
No, it's because nobody has submitted them for inclusion.
That's how everything that's in the docs already has got there.
If you have something worth adding, check on -doc that nobody's
already working on the same thing, sound out your ideas, and
send them to -doc for review. You could be surprised what makes it
through that process simply due to the absence of any alternative.
> Exactly .... maybe then we'd have official docs with words on the
> pages rather than simply chapter headings & virtually blank pages !!!
Exactly.
> Where I started with this thread was trying to discover if its
> reasonably feasable to write a step_by_step HOWTO about X-windows.
Please, please do! And please do it as part of the FreeBSD Doc Project
if you can. Then after it's done, you will become a role model who has
found an omission and gone on to correct it, and others might follow.
> >
> > Exactly what are we expecting newcomers to know, and
> > why can't we state those expectations clearly?
> >
> Thats a very good question & I'll be very interested to see the
> responses :)
Maybe some of the -doc people have thought about this.
--
Regards,
-*Sue*-
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010514103623.B68348>