From owner-freebsd-doc Fri Jul 12 13:18:31 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id NAA13181 for doc-outgoing; Fri, 12 Jul 1996 13:18:31 -0700 (PDT) Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id NAA13175 for ; Fri, 12 Jul 1996 13:18:28 -0700 (PDT) Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id UAA08336; Fri, 12 Jul 1996 20:18:27 GMT Message-Id: <199607122018.UAA08336@gatekeeper.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.4/16.2) id AA221222724; Fri, 12 Jul 1996 14:18:44 -0600 Date: Fri, 12 Jul 1996 14:18:44 -0600 From: Sean Kelly To: doug@sun1paztcn.wr.usgs.gov Cc: freebsd-doc@freebsd.org In-Reply-To: <9607121943.AA00232@sun1paztcn.wr.usgs.gov> (message from Doug Wellington on Fri, 12 Jul 1996 12:43:23 -0700) Subject: Re: Let's hack on the Handbook! ..my ideas... Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Doug" == Doug Wellington 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