Date: Mon, 12 Mar 2001 19:29:25 -0600 From: Mike Meyer <mwm@mired.org> To: David Johnson <djohnson@acuson.com> Cc: Doug Young <dougy@bryden.apana.org.au>, freebsd-questions@FreeBSD.ORG Subject: Re: documentation issues generally Message-ID: <15021.30709.531367.27409@guru.mired.org> In-Reply-To: <3AAD733E.CA29C3F9@acuson.com> References: <046701c0ab3c$c4a66300$847e03cb@apana.org.au> <15021.23142.119090.401764@guru.mired.org> <00f501c0ab57$0cf59760$0200a8c0@apana.org.au> <15021.29109.287302.175380@guru.mired.org> <3AAD733E.CA29C3F9@acuson.com>
next in thread | previous in thread | raw e-mail | index | archive | help
David Johnson <djohnson@acuson.com> types: > Mike Meyer wrote: > > In other words, you never even bothered trying. I've never read the > > docs list. I don't want to read about writing docs, I want to provide > > better docs to help people use FreeBSD, and cut down on the questions > > on -questions. I believe I've succeeded in doing that. > If that list is anything at all like the kde-doc list, I don't blame > Doug at all. DocBook is great and pretty easy to learn. But the people > who are really *into* DocBook have lost all sense of priority. They're > more into DocBook than into Documentation. That's actually the normal path for things to take. Those who are good at that kind of thing are drawn to it. As I pointed out later in that message, *it doesn't matter*. Those people are good at tweaking the tools, and making them turn out lots of different formats. Let them, and just ignore the list. It takes exactly two things to contribute usefully to the FreeBSD documentation project: 1) Track the docs sources. If you're properly tracking BSD otherwise, that means cutting the DOCSUPFILE line from /etc/defaults/make.conf, copying it to /etc/make.conf and uncommenting it. The next time you do "make update", you'll get the latest doc sources. 2) Install the docproj metaport. That's a huge port, and installs some stuff you may never need - but it installs everything you do need. When you want to change or add something, find the document where it's going to go in /usr/doc, and save a copy of the source. Edit the original, cribbing from the document you're editing as needed. The stuff it just like HTML, except it has a different set of tags and entities; anyone who can write a reasonable HTML page can do all this. When you're done, save it and type "make lint" in that directory. Now comes the hard part if you write HTML like most people - you have to find and fix the errors it lists. I've found that if you don't want to fix the errors, the committer generally will, but will ask you to fix them in the future. As Kris points out, if you don't write it marked up, they'll even mark it up for you - though it'll take longer, and they might grumble. But taking an existing text and reusing the markup is so easy, I don't see much point in not marking it up. <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.30709.531367.27409>