Date: Mon, 5 Apr 1999 23:05:36 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Darren Pilgrim <dpilgrim@uswest.net> Cc: Greg Lehey <grog@lemis.com>, junkmale@xtra.co.nz, FreeBSD Documenters <doc@FreeBSD.org>, advocacy@freebsd.org Subject: Re: Another Installation Guide [was: FreeBSD Advocacy] Message-ID: <19990405230536.A6083@catkin.nothing-going-on.org> In-Reply-To: <37091BA6.E80526DD@uswest.net>; from Darren Pilgrim on Mon, Apr 05, 1999 at 01:23:02PM -0700 References: <37053C70.A99BEB29@uswest.net>; <19990405164928.40818@welearn.com.au> <19990405071708.EHEJ5596385.mta1-rme@wocker> <19990405165231.O2142@lemis.com> <37091BA6.E80526DD@uswest.net>
next in thread | previous in thread | raw e-mail | index | archive | help
How do,
[ I've cc'd this to -advocacy, where a lot of the discussion still seems
to be happening ]
On Mon, Apr 05, 1999 at 01:23:02PM -0700, Darren Pilgrim wrote:
> Kinda. What got to me was the idea that if I wanted any support from
> FreeBSD at all, I would have to abandon my original prime objective;
> in which case it would be more productive for me to abandon the
> project altogether and volunteer for the FDP.
I've been trying to stay out of this, because I know that I'll only end
up writing an incredibly lengthy e-mail that'll just spawn another
round of long messages. But everyone else is having their two cents
(or whatever the local denomination is), so I may as well have a go.
First off, being listed as the Doc. Proj. Manager in the Handbook hasn't
imbued me with some mystical sense of what's the right thing to do, and
I'm willing to be argued out of most of what follows, if the arguments
are good enough, obviously.
Let me see if I can summarise; you've decided that the FreeBSD documentation
set is sadly lacking in easy to follow installation instructions, and you
want to fill this gap. Several other people have said (and I'm
paraphrasing) "You can't do this unless you do it in the Handbook, we
won't help you unless you put it in the Handbook, it won't be anything
to do with FreeBSD unless it goes in the Handbook." You think this is
a bad idea, and have almost decided to go off and code for Microsoft (or
something like that).
Possibly a touch over the top, but that's pretty much what it's coming
across as. :-)
Right. First things first. Thanks for volunteering to write documentation.
*Any* documentation. Documentation is massively underrated by many people,
and we need it, the more the better.
Secondly, the Handbook and the FAQ are not the be-all and end-all of online
FreeBSD documentation. The FreeBSD diary demonstrates this point well,
as does the work over at vmunix.com, as do the various other tutorials
that are linked to on the website (and some that, doubtless, are not linked
to from the website).
There's definitely room for material that does not fit within the framework
of the FAQ and the Handbook. It's entirely possible that this installation
guide falls into that category.
If you do decide that this should be a standalone work, don't think that
you won't get any support from this (and other) lists. There's no rule
that says "If it's not on www.freebsd.org then we don't want to know".
So, if you want to work on this in your own space, and with your own ideas
that's great. Solicit help in here (and on other, appropriate, lists).
Post URLs to work in progress, invite comments, and all the other stuff
you'll need to do to get a polished piece of work. And if anyone complains
about it not being a part of the Handbook, point 'em my way :-)
Having said all that, you might want to reconsider. Or at least consider
a little bit longer. Here are some of the attractions that making this
part of the Handbook can bring you;
<fx: puts on glitzy showman's suit>
* It's part of the main online resource for FreeBSD. Not the only
resource, but certainly the main one. As such, the Handbook needs
good documentation, and good documentation needs an audience. The
two would fit well together.
* If you make it a part of the Handbook, it will automatically be
mirrored over umpteen different web servers all round the world.
* As part of the Handbook, it will go on to all the FreeBSD CDs
produced by Walnut Creek.
* As part of the Handbook, it will be translated in to different
languages by the FreeBSD translation teams -- Spanish, Japanese,
French, German, to name but a few.
* You get commit access to the FreeBSD tree[1]
* You get to take advantage of the technology I've been integrating for
the past few months, allowing your carefully chosen words of wisdom
to be distributed as HTML, Postscript, PDF, RTF, DOC, . . .
* You get the send-pr system for people to submit changes to it to you.
* When you decide to take a break for a bit, other people can keep
maintaining it.
There's probably more, but they're the one's I can think of at this time
of night.
Of course, the bottom line is that it's your decision. I'd prefer it if
you worked within the framework of the Handbook (if nothing else, it means
one more person who knows how the Handbook works, and can commit other
people's changes, so spreading the workload around a bit more). But no one
here can force you to.
N
[1] Well, not immediately. Normally, it works something like this. You
send me (or someone else) some patches to the Handbook. We apply them.
They apply cleanly. We do this again. And again. And again. Pretty
soon I've got bored of applying all these patches myself when they work
first time, and I pester Jordan or one of of the others to give you
a login on freefall and commit rights.
--
Bagel: The carbohydrate with the hole
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?19990405230536.A6083>