Date: Thu, 3 Aug 2000 23:26:49 +1000 From: Sue Blake <sue@welearn.com.au> To: freebsd-newbies@freebsd.org Subject: Put up or sh... [was: new books, ...] Message-ID: <20000803232646.G36915@welearn.com.au> In-Reply-To: <01be01bffcca$40e8b890$847e03cb@ROADRUNNER>; from Doug Young on Thu, Aug 03, 2000 at 07:40:15AM %2B1000 References: <DBB3921EFE2AD211A81500A0C9B5FE7605794533@msg04.scana.com> <01be01bffcca$40e8b890$847e03cb@ROADRUNNER>
next in thread | previous in thread | raw e-mail | index | archive | help
Look out, Aunty Sue's back :-)
On Thu, Aug 03, 2000 at 07:40:15AM +1000, Doug Young wrote:
>
> > The problem lies in the gap between experienced UNIX admins and
> > inexperienced UNIX users, like myself (striving to be an admin).
> > Certain knowledge of UNIX is assumed, not purposely by the doc
> > writers, but the doc writer already have this knowledge. Many
> > "newbies" simply don't have this knowledge.
Exactly. Look at my ancient newbies page on the FreeBSD web site.
(There's a link to it on the main page, but of course you know that.)
It groups the information into three categories: FreeBSD, UNIX, X.
FreeBSD isn't directly responsible for helping with general UNIX or X
skills, although they are necessary prerequisites to working with
FreeBSD. Other places probably document them better or more thoroughly,
which is why the newbies page did include links to other sources for
that information, and FreeBSD sources for information specific to
FreeBSD. Of course there are a few writings about general UNIX skills
and X from a FreeBSD perspective, too.
Now why do you think the newbies page is so ancient and sparse? Many
reasons, but the two main ones are my own apathy, and the lack of
feedback and suggestions I received. You people are supposed to tell
me, either personally or here on the list, what you like or don't like
about it and what you would like to see added. The page tells you so.
In all the time it's been there I've heard hardly a peep from newbies.
Does anyone ever look at it, apart from the three or four people who
wrote to me ages ago? Because if not, we shouldn't have it at all.
Next on the agenda was to prepare and keep up to date a page listing
all FreeBSD-related documentation particularly suitable for newbies, in
many cases written by newbies or near newbies. After some discussion
here many months ago we agreed that most of what people wanted was
around somewhere, it was just too hard to find. I jumped through many
hoops to get web space for such a page, the permission required to be
able to go in and update it very frequently, and official blessing for
such a page existing on the FreeBSD web server. I asked for
suggestions, heard two pins drop, then silence.
So guys, here's a challenge. Write to me personally with URLs of
FreeBSD newbie-oriented sites and web pages etc that you think are useful.
Write again when you think of some more. I'll review them if necessary
(we don't want very incomplete or misleading sites to put people off)
and put up a web page on the FreeBSD.org server where everyone can find
it, and update it as new info comes in... IF you guys do your bit. You
don't have to write the damn stuff (but don't let me stop you!), you
just have to keep me updated.
Deal?
> This is something many of us have been saying for ages .... its because the
> people who write docs are typically extremely experienced that they are not
> the ideal people for the job. This issue is not something peculiar to
> FreeBSD, but certainly the situation is far worse with open source software
> than with commercial equivalents.
>
> > It almost seems an insult to those that document FreeBSD to have
> > simple step by step instructions on doing very specific mundane tasks,
> > however this is what many of us require.
>
> Ummmm .... I just checked this was the right list, but yes it IS the
> "newbies" one so discussion relevant to newbies is presumably on the
> allowable list of topics ... heated or otherwise !!!!!
Absolutely! Try not to get too heated yourself, but be aware that many
other newbies are not used to expressing themselves with restraint in
email. Better to get it out in a semi-closed environment like this list,
than to sweat over it or blurt it out where people are less forgiving.
You can all help the emotional writers to relax a bit by giving them moral
support in a more standard writing style, and if ever you get carried
away yourself, someone will be here listening to you too.
When I started this list, way back when, one of the main things it
hoped to achieve was more and better documentation for newbies, either
written by newbies or enhanced by feedback from newbies. Some have
risen to the task, joined the -doc list and made some good
contributions in one way or another. I don't think the others show
laziness, I think it's inhibition and lack of familiarity with the way
things get done in an anarchy. As a newcomer you tend to "see" rules
and bosses everywhere, not realising most of them are unofficial
displays of ego. It's easy to be scared off by someone who sounds very
competent and much more knowledgeable than yourself. (See, you're
hanging on to my every word right now, aren't you :-) Here you get to
discuss with others as equals, without the heavies intruding. Hopefully
that gives some of you the confidence to wander off into the more
standard work rooms sooner or later.
If you are very new, about now you'll be getting used to the idea that
"they" don't have to write docs for you, because there is no "they".
Everyone who can write something and has the time to do so, does. They
write what they feel like, when they feel like writing, because they
feel like it. If and only if people benefit from the documents AND tell
them so, they'll likely keep on writing.
In most cases the writing is sufficiently useful and acurate that it is
snapped up by the FreeBSD Documentation Project. Some people prefer not
to give their writings back to the project and set up their own
separate site somewhere, and that's OK too. At least they're writing.
Many newbies who cannot write have contributed to -doc by reviewing new
documents to offer a newbie's perspective. Do a good reliable job at
this and high tech document authors will be queueing for a space in
your busy schedule, and throwing more docs your way than you'd ever
hoped to see.
Other newbies have written a simple thank-you note to the writer of a
document, saying why they liked it and what was helpful about it.
Because of those tiny little pieces of feedback, some doc writers who
had drifted off have come back to write more. You see, nobody had ever
bothered to thank them before so they thought their work wasn't useful,
or that newbie-oriented works were never read by anybody. It is
generally agreed that the best praise a document can get is heartfelt
praise from a newbie!
Also, don't fall into the trap of the "if you build it they will come"
fallacy. We've had newbies get all fired up, go off and learn PHP and
Java and assembler (OK, I exaggerate a teensy bit) and put together a
technological marvel to "solve" the shortage of newbie docs. They slog
their guts out and omit the one thing that was missing all along: the
DOCUMENTS, the PLAIN OLD WORDS.
Like Neil said, it doesn't matter what format they're in. Ordinary
ASCII text is very nice, thank you. What we need is the words to
explain stuff, and the signposts that point people to where the words
can be found. It's a good idea to discuss what you're writing so that
two people don't work on the same thing without knowing, and that's
where the -doc list is important. But no matter, if you would like to
have a go, start now. At the prompt type 'ee' or 'pico' or 'vi' and
hey, you're a documenter!
--
Regards,
-*Sue*-
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-newbies" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000803232646.G36915>