Date: Wed, 18 Oct 2000 14:46:54 +0100 From: Steve Roome <steve@sse0691.bri.hp.com> To: Jordan Hubbard <jkh@winston.osd.bsdi.com> Cc: peter@sysadmin-inc.com, "'Jason C. Wells'" <jcwells@nwlink.com>, freebsd-doc@FreeBSD.ORG Subject: Re: How To's [about to get flamed] Message-ID: <20001018144654.C25899@moose.bri.hp.com> In-Reply-To: <64326.971803991@winston.osd.bsdi.com>; from jkh@winston.osd.bsdi.com on Tue, Oct 17, 2000 at 10:33:11AM -0700 References: <peter@sysadmin-inc.com> <64326.971803991@winston.osd.bsdi.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Oct 17, 2000 at 10:33:11AM -0700, Jordan Hubbard wrote: > > short step by step "here's how to get it running" documentation would do me > > a lot of good. > > The obvious problem is that the documentation for FreeBSD is written > just like its code - by volunteers. Most volunteers are also not > tremendously motivated to write docs unless it's because they're > frustrated enough with the state of some bit of documentation to > either improve or write it from scratch. > > That state of frustration generally doesn't occur but once, when > initially grappling with a problem just as you are now. > Unfortunately, most people who work through issues like this don't > stop to write up their experiences and thus leave a paved road for > others to follow, they simply sigh with relief and move on to the next > problem. You see the catch-22 in this situation? :-) This is long, and not intended to offend anyone. Jordan, I think you see the problem very differently to others! Personally, I've used FreeBSD for a large amount of stuff, and I've set up far more boxes than I can remember. I've even documented quite a bit of the process. There's one of those "Connect your Office" type products on the market that I wrote (I think we started pushing them out before the InterJet made it's name!) - completly using FreeBSD. But after using FreeBSD almost daily since v2.0.5 I've only contributed about one page of (badly written!) documentation to the FAQ. This is because it's so damn difficult to contribute anything for most of us. Maybe not for you, but that's different! But for anyone else, it's a pain. The few people we need to talk to are often not that helpful (although I think this is improving). But sometimes are downright rude and arrogant. Sometimes even assuming that because we are not already commiters or -core then we must be a bunch of thickies, possibly true. But it's not good for the project! The way newbies are sometimes treated has been done to death before I think, but it's still fairly true. As others (and no doubt you) have said before, FreeBSD is *OUR* project, we all *OWN* it. But sadly so many of the people I have worked with on FreeBSD have given up trying to help. The only guy out of the whole BSD crowd I know who has done anything is Nik Clayton. But I hardly know him, more of a friend of a friend. When I look at the Linux HOWTO's I see that they probably have a different attitude. It appears to me that they let almost anyone commit a new doc. Whatever the quality, it goes in. Sounds bad doesn't it! But there's only a limited number of docs to write, no doc for something and people will all go off and learn themselves. Or switch to some other platform. One poorly written document on something though, and I can see queues of people saying how bad it is, and how to change this and that, and then there will be people improving it. Better than nothing. But often, at least IMHO, we seem to have a policy of "if it's not perfect we don't touch it". Things don't always start out that way. Perhaps we need a sort of "call for papers", everyone with any docs on FreeBSD should send them somewhere and we need to do something with them, put them in a contrib docs section. Any format would be fine, because at least we get the docs that way. We can worry about sgml later if it's really needed. Then again, the odd word doc and pdf would probably be a good thing. Mgmt like those sorts of things, even if none of us techies actually have word! At the end of the day, I've done a bit of DNS work in the past, well, I ran 50+ domains off a FreeBSD box, which is enough for me. Until recently I'd not used the new syntax in bind, and when I wanted to learn, I read the Linux HOWTO. [The manpage is better, but harder to get anywhere with at first.] We don't have a bind 8 howto. (because we don't do howto's as someone rather snobbishly stated earlier in this thread!) But I'm sure a lot of folks would improve on one if we did have something of the sort, in the end we'd have better -docs. Steve P.S. Yup, just finding my flameproof hat now. 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?20001018144654.C25899>