Date: Mon, 16 Mar 1998 04:03:24 -0800 From: "Jordan K. Hubbard" <jkh@time.cdrom.com> To: Studded <Studded@dal.net> Cc: FreeBSD-Stable@FreeBSD.ORG Subject: Re: Documentation plan? Message-ID: <7061.890049804@time.cdrom.com> In-Reply-To: Your message of "Mon, 16 Mar 1998 01:50:30 PST." <350CF5E6.5DD147F5@dal.net>
next in thread | previous in thread | raw e-mail | index | archive | help
> Oh, no argument there. Well, you asked, so you shall receive. Excellent - a maso^H^H^H^Hmanager steps forward! > 1. I think that there is universal agreement that the first priority > needs to be "up to the minute" pages where all important announcements, > especially related to the upgrade procedure for -Stable and -Current > will be posted. I think two pages is the best plan, one for each branch. Yep. These need to be both created and maintained on an ongoing basis. We've made a few false-starts at the former and never even come close to the latter. :-( It takes dedication on the order of a Doug White (-questions) or a Steve Price (GNATS) to do this adequately, just to elevate those two to Icon status. ;-) > 2. I personally think that the second priority would be to overhaul the > documents in the root directory of the ftp site (and by extension the > CD). There is too much duplication and no coherent plan. I'd break it up Absolutely. That basically describes most of our docs, not just the FOO.TXT files. What we have is the result of haphazard evolution over the last 4 years rather than any coherent design, and just like any reasonably large body of code, you *must* plan on essentially throwing out the first effort and starting over. This hasn't happened yet. :) > README.TXT - Short, general introduction, table of contents similar to > the following, including some of what's in ABOUT.TXT now. Add a more > prominent pointer to the www page in general and put a reference to the > new "important info" page above close to the top. > [other FOO.TXT suggestions elided] I'm all for that, I just need something to start with. I've been looking at the FOO.TXT files for too long to be properly objective any longer. > 3. The next priority as I see it is 3 or 4 people to read every word of > the FAQ and Handbook and point out areas that are out of date. (Are Or just start over, using the bones of the previous effort as a starting point. There's some good meat there and a lot of fat. > As I said, I'd be happy to help with this project, and I can spend some > time with the docs themselves as well. If no one better suited steps > forward I would be willing to coordinate things provided there are > actual volunteers to coordinate. :) That being said, I certainly think If past experience is any thing to go by, if you're capable of yelling "CHARGE!" with enough reasonable authority, the volunteers will appear. ;) Jordan To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?7061.890049804>