Date: Mon, 12 Mar 2001 17:23:18 -0600 From: Mike Meyer <mwm@mired.org> To: "Doug Young" <dougy@bryden.apana.org.au> Cc: "Duke Normandin" <01031149@3web.net>, "David Johnson" <djohnson@acuson.com>, <mij@osdn.com>, <freebsd-questions@FreeBSD.ORG> Subject: Re: documentation issues generally Message-ID: <15021.23142.119090.401764@guru.mired.org> In-Reply-To: <046701c0ab3c$c4a66300$847e03cb@apana.org.au> References: <046701c0ab3c$c4a66300$847e03cb@apana.org.au>
next in thread | previous in thread | raw e-mail | index | archive | help
Doug Young <dougy@bryden.apana.org.au> types: > Seems like the docs situation is destined to keep going the same route as > present. Its quite obvious that the "official" docs people are more > interested in the systems used to create docs than the content thereof. The way to deal with that is, of course, to submit improved documentation to them. They seem both responsive when it comes to adding submissions from other people, and appreciative of receiving them. They are more responsive and more appreciative if you mark the submissions up properly, as that leaves less work for them to do. But their markup language is easier than modern HTML, and lots of people have learned that. > I personally don't believe there is any point in submitting material to > freebsd-docs ... I favour an infinitely more user-friendly format (eg Have you tried submitting something in that format? If not, what did you base this conclusion on? As indicated above, my experience submitting things has been pretty good. > including a bunch of screen dumps, step_by_step examples & "real world" > examples of typical commands) rather than the mind numbing synopsis > style complexity of the man pages. Trying to use the man pages to learn FreeBSD is like trying to use Websters to learn english. I'd expect the results to be mind numbing in either case. > Maybe the man pages aren't the "correct" > place for explicit explanations, but if thats the case then the Handbook > certainly is. I was just thinking that. And was going to suggest that if you wanted to contribute to the project, going through the handbook, writing down every word that you needed a definition and it's section title and then sending that to me - or -questions - to get definitions. Iterate over that list until you think the results are acceptable. Finally, PR the thing. > To be fair its definitely an improvement on what it was a year > ago & light years ahead of most of the linux equivalents, however the screen > dumps /examples / etc are still conspicuous by their absence. Yes, it's a lot better than it was a year ago. That's because users stepped up and improved it. And yes, it still needs improvement. I've submitte FAQs and man pages and have got a handbook entry I'm about to submit. Some of them even include examples. > OK so some of > the user-friendly sites have errors .... at least they make an honest > attempt to provide information in an intelligible form which is something > still lacking in the official documentation. The blame for that documentation not being in the official FreeBSD documentation should not be layed on the authors of the FreeBSD documentation; it should be layed on the authors of those sites. There are places for almost all of that in the official documentation, and they probably could have gotten it accepted if they had submitted it. The bottom line is that FreeBSD is a an open source volunteer project. "Volunteer" means that nothing gets done unless someone steps up to do it. "Open Source" means anyone who wants to has the information they need to do that. If you think something in FreeBSD sucks, you can fix it, so just do it. <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?15021.23142.119090.401764>