Date: Wed, 29 Nov 2000 14:42:52 +0000 From: Nik Clayton <nik@freebsd.org> To: Rich Morin <rdm@cfcl.com> Cc: freebsd-doc@freebsd.org, scrollkeeper-devel@lists.sourceforge.net Subject: Re: draft article, for review Message-ID: <20001129144252.A23325@canyon.nothing-going-on.org> In-Reply-To: <p0500191eb6485fe68c33@[192.168.168.205]>; from rdm@cfcl.com on Mon, Nov 27, 2000 at 11:09:54AM -0800 References: <p0500191eb6485fe68c33@[192.168.168.205]>
next in thread | previous in thread | raw e-mail | index | archive | help
Rich, On Mon, Nov 27, 2000 at 11:09:54AM -0800, Rich Morin wrote: > I have written up some recent experiences with FreeBSD documentation > for my column (Silicon Carny) in SunWorld (http://www.sunworld.com). > The column also attempts to summarize the aims of the ScrollKeeper > and Meta Projects. > > If you would like to look at the draft I'm submitting, take a look at > http://www.cfcl.com/rdm/SC.200012.1. Please send me email (in the > next few days) about any problems you notice. I should be able to > squeeze in a few changes during final edit... I'm keeping the cc's in place for this, because this is something I want to reiterate to the commentators and lurkers on the FreeBSD-doc mailing list (and the various Linux doc people on the ScrollKeeper list will probably agree). We're in complete agreement about the need for better documentation, and the requirement for better searching and indexing tools. Of this latter requirement, I have high hopes for ScrollKeeper (once we've finished batting around some of the design decisions). Your choice of make.conf is perhaps a little unfortunate, as in the past few weeks someone else has had exactly the same problem you had. They also realised that a make.conf manual page would be a good thing to have for the reasons you specify in your article. So, they wrote one, put together a PR (Problem Report, or Patch Report, depending on who you listen to), visible at http://www.FreeBSD.org/cgi/query-pr.cgi?pr=22676 As you can see, this was then kicked back and forth a bit on the mailing list, changes were made, and then it was committed to FreeBSD. So FreeBSD, thanks to the actions of one of its users, now has a make.conf(5) manual page. I don't doubt that there are other areas of the system that need further documentation and explanation. It's an unfortunate fact of life for all of us that there are this > < many things to do, and this > < much time in which to do them. This is why the FreeBSD project is very open to receiving PRs, and I do my level best to bring people in to the doc project as soon as they demonstrate that they can generate good PRs and won't need an excessive amount of handholding. In the recent past this includes people like Bruce Mah Ben Smithurst Mark Ovens Daniel Harris Kazuo Horikawa Hiroki Sato Alexander Langer and many others (Neil, Sheldon, Jeroen, the list is long, and an omission just means I haven't got time to work through CVSROOT/access). This is how the process works -- people find problems, fix them, and submit patches. Sometimes the people finding the problem are already committers, but a lot of the time it's FreeBSD users. And with the best will in the world, a PR with a patch is a hell of a lot easier for a committer to deal with than a message saying that something needs fixing. [ For example, the fact that sysinstall doesn't know about the new documentation packages yet -- I know this is a problem, as do people following this mailing list. But unless someone else steps up to the plate (anyone!) with patches, the problem's going to have to wait until I've got the requisite 12 clear hours to sit down with the sysinstall code and write the glue. ] N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery 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?20001129144252.A23325>