Date: Tue, 17 Mar 1998 00:16:55 -0800 From: Studded <Studded@dal.net> To: "Jordan K. Hubbard" <jkh@time.cdrom.com> Cc: FreeBSD-doc@FreeBSD.ORG Subject: Re: Documentation plan Message-ID: <350E3177.8F52760C@dal.net> References: <7061.890049804@time.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
[ Moved to -doc. ] Jordan K. Hubbard wrote: > > > Oh, no argument there. Well, you asked, so you shall receive. > > Excellent - a maso^H^H^H^Hmanager steps forward! Actually my personal bent is more the other way, but I digress. :) > > 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. ;-) Ok, we need a volunteer. It needs to be someone with commit privileges to get the thing started, and then someone who can politely but firmly prod people into keeping it up to date. Unless I misunderstand, any committer can make www changes, yes? So people could be resonsible for their own "updates." I think Nik would be a good person for this, but perhaps there is someone else interested? > > 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. :) *Nod* I agree that the whole thing needs to be redone, but that pesky time/space problem forces us to prioritize re things that are soon to be stamped into a CD. :) > > 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. Well I was thinking more along the lines of parcelling this stuff out, unless you want to take responsibility for README.TXT? > > 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. Agreed, but that's not going to get done before 2.2.6. Getting some "users" to look through the docs and pick out the really glaring stuff before it gets stamped would be a good step. I'm looking towards increasing the value of the CD in the short term. > > 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. ;) Well I already have two, so I guess that's a good sign. :) Since the FOO.TXT stuff doesn't require privileges, without objection I'll post to -questions and maybe -chat tomorrow asking for more volunteers and get them going. I'd like to make the 23rd the deadline for the working drafts, and the 27th the rock solid deadline. Jordan does that work for you? Since the docs don't affect how things "work" it seems that cutting it that close wouldn't be a problem, let me know if I've assumed incorrectly. Doug -- *** Chief Operations Officer, DALnet IRC network *** *** Proud operator, designer and maintainer of the world's largest *** Internet Relay Chat server. 5,328 clients and still growing. *** Try spider.dal.net on ports 6662-4 (Powered by FreeBSD) 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?350E3177.8F52760C>