Date: Fri, 12 Jul 1996 14:18:44 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: doug@sun1paztcn.wr.usgs.gov Cc: freebsd-doc@freebsd.org Subject: Re: Let's hack on the Handbook! ..my ideas... Message-ID: <199607122018.UAA08336@gatekeeper.fsl.noaa.gov> In-Reply-To: <9607121943.AA00232@sun1paztcn.wr.usgs.gov> (message from Doug Wellington on Fri, 12 Jul 1996 12:43:23 -0700)
next in thread | previous in thread | raw e-mail | index | archive | help
>>>>> "Doug" == Doug Wellington <doug@sun1paztcn.wr.usgs.gov> writes:
Doug> I agree that there isn't enough material YET. Maybe my
Doug> delusions of grandeur are getting ahead of me... ;-)
No problem ... I still have this unusual recurring dream where I see
the corporate campus at Microsoft rendered a heap of rubble by a pudgy
red daemon proudly brandishing a pitchfork. :-) (Of course, being a
dream, suddenly I'm naked in my 4th grade class having to take a test
on multiplication.)
Doug> Hmmm, yes, we must use separate definitions... I look at
Doug> the Handbook and see programming info in chapter 4.2 (ports)
Doug> and I consider section IV to be almost completely
Doug> programming.
Okay, I think I see from where you're coming. And it a way it does
make sense! ;-)
Doug> There are indeed many many areas that need to be covered
Doug> before we can have three "complete" Handbooks. However, I
Doug> think now is the time to determine the structure the
Doug> documentation will be in, now and for the future, BEFORE we
Doug> get too much data to easily manipulate...
You've got a point. And now I want to waffle on what I said about
there not being enough material to justify splitting. One thing that
I recall seeing during the last official FreeBSD release was that the
handbook was too long to print. Several people wanted just certain
sections---they needed to know how to set up PPP and how to use the
ports collection but didn't care about printers, for example.
The handbook is over 300 printed pages now (right?) and maybe it would
be a good idea to split it up ... after all, we're certainly not
*removing* any material, are we?
Doug> And I would also like for FreeBSD to appeal to
Doug> those who don't know. I think there are a lot of people who
Doug> WANT to program, but who can't afford the cost (and the
Doug> learning curve!) of Windows and VC++ or a Mac with whatever
Doug> their latest tools are.
You bet. Despite all the arguments from the Unix Haters, I think Unix
still makes an efficient development platform---just not the
prettiest. To me, a handbook called `Developing with FreeBSD' should
not exist unless we integrate Raynard's development tutorial into it.
Such a book needs a section to get users started, and his tutorial
could do that.
>> And all the other people are using FreeBSD to provide Internet
>> services.
Doug> Hmmm, then am I the only one who decided to just "use" it to
Doug> write papers and to dial in to an ISP?
I admit it: I lied in that statement. My wife uses FreeBSD for her
Ph.D. research and to write papers. (I use it for hobby programming,
home automation, work, and to write papers.)
Doug> Who are we trying to appeal to with FreeBSD, an elite core
Doug> of programmers?
Being merely a contributor, I really can't say in what the direction
the FreeBSD ship is steered.
Doug> Should we just put a statement in the introduction to effect
Doug> of, "If you just want to have an operating system to learn
Doug> and use, why don't you try Linux instead..."?
Egads, no! What I meant to say was that I'd wager many people using
FreeBSD are doing so to provide Internet services. Glance at the
FreeBSD Gallery and you'll see that the majority of commericial
applications are ISPs. Therefore, at least some part of our
documentation should be directed at them.
Certainly, there could be an even greater number of people who are
home- or research-style users of FreeBSD, who aren't represented in
the Gallery. Therefore, at least some part of our documentation
should be directed at them.
In an ideal world where we have competent writers who are knowledgable
for each topic and have plenty of time in which they can profess their
art, then we'd address both audiences with thorough, usable,
understandable, correct, documentation. Since this world isn't ideal,
we then need to measure which audience has the best return value and
write to that audience first. What is the return value?
Unfortunately, too many things to make an adequate metric: FreeBSD
name recognition, commercial support, ported products, monetary
contributions, etc., and other things that help insure the survival of
the project and the eventual defeat of both Linux and Bill Gates. :-)
Anyway, let me close this up before someone mistakes me for Mr Lambert
(no offense ;-). This is a volunteer project in the end and if
someone's capable of measuring the audience's return value and of
writing documentation to that audience, fine. Personally, I can't
make such metrics---nor can I write a manual on setting up web servers
or mail (Usenet, maybe, but back in the old C-news days ... does
anyone C-news anymore?). But I can write a chapter on how to do RPC
programming on FreeBSD or how to access the floating point facilities
in the C language. So, let those who can contribute what they can
contribute, contribute!
Sean Kelly
kelly@fsl.noaa.gov
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199607122018.UAA08336>