Date: Mon, 12 Mar 2001 09:04:33 -0600 From: Mike Meyer <mwm@mired.org> To: "Doug Young" <dougy@bryden.apana.org.au> Cc: <questions@FreeBSD.ORG> Subject: Re: documentation issues generally Message-ID: <15020.58753.851419.958480@guru.mired.org> In-Reply-To: <036d01c0aafd$e519e060$847e03cb@apana.org.au> References: <15020.55044.631599.345193@guru.mired.org> <036d01c0aafd$e519e060$847e03cb@apana.org.au>
next in thread | previous in thread | raw e-mail | index | archive | help
Doug Young <dougy@bryden.apana.org.au> types: > > Yes. Improve them, then submit PRs with the improvements. > Been there done that .... the docs people speak another language again !!! Just curious - how many man page or doc project PR's did you submit before reaching this conclusion? In any case, if nobody writes them to meet your requirements, they aren't going to get written. If you're not willing to write them, why do you expect other people to do so? > > > Has anyone ever considered the possibility that documentation > comprehensible > > > to regular users might cut down on the hundreds of questions posted to > this > > > list daily ?? > > I'm sure it would, by at least a few percent. I wouldn't expect it to > > cut down much more than that, because that's the percentage that seems > > to have both read the appropriate documentation and failed to > > understand it. > How then do you explain the growing number of sites like freebsddiary ?? Because people would rather put things on their own sites than submit them to the FreeBSD group and have them show up there. While this may be good for their site, it's bad for the FreeBSD community. If nothing else, it means that users have to search multiple sites to find the the documentation they are looking for - and may find different directions. For another, it means that the FreeBSD team doesn't get a chance to vet the instructions. Personally, I *never* refer people to those sites. The ones I've looked at don't seem to be any better written than the FAQ or the handbook. They do provide detailed step-by-step instructions, but but those instructions are often more complicated than needed, sometimes wrong, and almost never include the information you need to understand what's going on. I *do* regularly refer people to FAQ, handbook and manual entries, and more often than not, that is sufficient to solve their problem. IIRC, your problems started with the man page for the filesystem dump program, but you weren't quite clear on what a filesystem is. The man pages are *not* the place to teach FreeBSD terminology. Neither is the FAQ - after all, if you don't know the terminology, you can't phrase the question. The handbook touches on it somewhat. But at this level, you're not really dealing with needing documentation on FreeBSD, but on Unix administration. There are a number of good books out there - and I've heard good things about Gregs. <mike -- Mike Meyer <mwm@mired.org> http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?15020.58753.851419.958480>