Date: Wed, 2 Aug 2000 23:50:59 +0200 From: Neil Blakey-Milner <nbm@mithrandr.moria.org> To: "SILVER, MICHAEL A" <MSILVER@scana.com> Cc: "'freebsd-newbies@freebsd.org'" <freebsd-newbies@FreeBSD.ORG>, 'Rick Hamell' <hamellr@aracnet.com>, 'Doug Young' <dougy@gargoyle.apana.org.au> Subject: Re: new books, changing my pt. of view Message-ID: <20000802235059.B37594@mithrandr.moria.org> In-Reply-To: <DBB3921EFE2AD211A81500A0C9B5FE7605794533@msg04.scana.com>; from MSILVER@scana.com on Wed, Aug 02, 2000 at 04:42:07PM -0400 References: <DBB3921EFE2AD211A81500A0C9B5FE7605794533@msg04.scana.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed 2000-08-02 (16:42), SILVER, MICHAEL A wrote: > the simplest things with out them. You would be challenged to find better > and more up-to-date documentation on any other free software. Thanks for your comments and praise; I'm sure the individual authors would love if you sent them an email if you find one of their sections particularly useful. > 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. I agree wholeheartedly, but the "newbies" (including me sometimes) shouldn't hesitate to contact the doc writers if they gloss over something. I'm sure none of them would mind adding a link to where to find introductory information on topics glossed over in their section. > 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. I can assure you that noone will be insulted by clear, easy-to-understand instructions, even the most hard-core systems administrator. Cryptic things irritate everyone, trust me! The number of times I've seen some of the kernel hackers wishing that certain systems were explained better... (: > I don't know how this would fit into the current documentation > project. This really should be a separate "how to" or example manual. The documentation project is growing quite rapidly, and there are a set of handbooks (the original handbook, the porters handbook, and the to-be-created developers handbook and users handbook) which will cover largish amounts of stuff in "reasonable detail". There are currently two "primers", which cover ppp and the FreeBSD Documentation Project at great depth. There are also a number of articles (some of them suffering from decay), such as the (new and undecayed) dialup-firewall recipe-like article, the committers guide, and the (much decayed) new-users article. They are intended to cover one subject or task in good, easy to use, instructions, but don't quite go as in-depth at the primers. I'm sure there is easily enough place for any documentation pertaining to FreeBSD. > Neil, how can we help with the documentation project? Everyone in the documentation project intends to trawl through the mailing lists, and turn all problems and solutions into a working document. Of course, time moves against us, since going through a week's problems and solutions probably takes a good two weeks ;). The first, and easiest, way to help is simply to notify the project that there is an issue with the documents. It can be as simple as sending mail to doc@FreeBSD.org, with your concerns. If you want to make it much easier for us, try use send-pr (there's a web interface for that too). If you have trouble with either, feel free to ask me. The second way is to write up something when you've had a problem, and found a solution. It may end up going into the FAQ, or into the handbook in an obvious place, if it is small. If it is large, you may find yourself the next darling of the documentation project, and have a full-fledged tutorial going. (: A third way is to join the doc@FreeBSD.org mailing list, and give suggestions where you can. It probably has more messages than here, so it might be a problem for some of you. > How can we build a document that will help new people setup and > configure FreeBSD? I think the Handbook has great content for > newbies, sometimes. Somehow we need to fill in the gaps, before we > can no longer appreciate the needs of the newer users. (if that made > any sense) I think the answer is: "The way we've always done them." FreeBSD is an example of a community-driven project, which, in my opinion, has gone right. It is self-sustaining because enough people who use it, contribute back to it by means of problem reports, patches, development time, and even money sometimes. I'm sure this can easily apply to the documentation project (and, if I may say so, it hasn't done a terrible job so far). If I may pretend to advise - If you don't let anybody know about your problems, and you don't fix them yourself, then you're suffering without reason. Neil -- Neil Blakey-Milner Sunesi Clinical Systems nbm@mithrandr.moria.org 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?20000802235059.B37594>