Date: Mon, 16 Mar 1998 01:50:30 -0800 From: Studded <Studded@dal.net> To: "Jordan K. Hubbard" <jkh@time.cdrom.com> Cc: FreeBSD-Stable@FreeBSD.ORG Subject: Re: Documentation plan? Message-ID: <350CF5E6.5DD147F5@dal.net> References: <5889.890037206@time.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Jordan K. Hubbard wrote: > > > Ok, so last night we had all this great momentum, lots of great ideas > > kicked around, and today nothing? Do we actually want to make some > > improvements here? Do we want them in time for 2.2.6? Jordan do you > > want to lay out a plan and have people volunteer to take bits? I don't > > I simply don't have the time - someone else, as I've already said, > will need to play "leader" here and get everyone aligned behind a > common plan and then make sure that they all stick to it until it's > actually completed. Ah, I was unclear on the somebody else part. :) > Contrary to popular opinion, management is also > Real Work(tm) Oh, no argument there. Well, you asked, so you shall receive. For 2.2.6: 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. I think that if we can get someone to make a framework template (as in a duplicate of template that the other pages are based on) then each person who commits a big change (like the new slice code) can put up a blurb about it and amend as necessary. Then we train people to use this page as a first resource for important news. For example the committer who makes the change can post to the appropriate list something to the effect of, "I just made an important change to the foo code, details can be found on http://www.freebsd.org/stable-news.html." (Name/URL for the page is open to improvement. :) 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 this way: 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. INSTALL.TXT - Overhaul this a bit, add answer to the -questions FAQ, "what do I download?," move all info on upgrading to, UPGRADE.TXT - Information specific to upgrading. Pull the info from from various of the files already there, and improve/streamline/add to it. (I think someone is already working on this?) HARDWARE.TXT - This is actually in pretty good shape. ABOUT.TXT - Consider losing this, the info that's there should basically be in other places. IMPORTNT.TXT - Capsulized version of whatever is on the "news" page when 2.2.6 goes golden, plus tidbits like /etc/sysconfig -> /etc/rc.conf, etc. RELNOTES.TXT - Ideally, someone knowledgeable should diff 2.2.5 and 2.2.6 and make a list. (Yes, I'm serious.) Barring that, we need as much good, detailed information about the changes as possible, preferably with the big shiny things up front, then broken down into "Different from 2.2.5, Different from 2.2.2, Different from 2.1," etc. 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 these the only docs that go on the CD?) This would be a great "entry level" point for someone who wants to help but doesn't have much technical writing experience. Post 2.2.6: 4. For the long term, I think we need a team to seriously consider the task of consolidating the current FAQ/Handbook/Tutorial situation into a more coherent whole. We have a lot of good information available, but through duplication of effort subtle problems and areas of confusion have set in which make it difficult for the average user, especially one new to Unix to deal with. I proposed a single entry point model with a "How do I?" type interface which accesses the newly organized and streamlined docs. :) This would be accompanied by pages similar to what we have now giving direct access to the new Handbook of course. This should be discussed further and a *concrete* plan laid out before any changes are made. 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 that what I've proposed bears discussion before we move forward. I think I've identified the urgent needs pretty well, but comments and suggestions from other perspectives are of course welcome and needed. Hope this helps, 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-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?350CF5E6.5DD147F5>