Date: Tue, 10 Jul 2001 04:32:47 -0700 From: Dima Dorfman <dima@unixfreak.org> To: Nik Clayton <nik@freebsd.org> Cc: doc@freebsd.org Subject: Re: State of the Handbook Message-ID: <20010710113247.A2B863E28@bazooka.unixfreak.org> In-Reply-To: <20010710114034.E16152@clan.nothing-going-on.org>; from nik@freebsd.org on "Tue, 10 Jul 2001 11:40:34 %2B0100"
next in thread | previous in thread | raw e-mail | index | archive | help
Nik Clayton <nik@freebsd.org> writes: > 2. Supplement the ASCII art with images. > > Something else on WRS' todo list, although it doesn't prevent anyone > else with an artistic bent from picking some of the existing ASCII art > and producing images for it as well. WRS expect to have this done by > the end of August. Do we have a mechanism so that we can keep the ASCII art and display it where necessary? I.e., I'd rather not see the ASCII art thrown away; not everybody wants to start a graphics-capable browser to read the docs (I know I don't). > 3. Stylesheet and wordlist > > We're quite inconsistent about the use and spelling of terms, > and the stylesheet for authors is quite small. We're talking to > O'Reilly about the licensing behind their stylesheet and wordlist > at http://www.oreilly.com/oreilly/author/stylesheet.html and the > possiblity of making this available to all open source documentation > projects (probably as a guide). I'm not quite sure what this is. Is this a stylesheet as in a DSSSL stylesheet? It seems that the link above is what we need; it talks about how certain things should be written, etc. Do we need a license to look at it? Or am I missing something? > 5. Integration of Randy Pratt's install guide to replace much of the > existing material in chapter 2. I haven't read Randy Pratt's install guide, but just about anything is better than the outdated stuff we have! Unless somebody else (e.g., Randy Pratt) wants to do this, I will (or I'll check in someone else's patches to do it). > 6. Licensing > > Some sections of the Handbook are under inconsistent copyrights > and licenses. I (nik) would like the entirety of the Handbook (and > indeed, the FreeBSD docs as a whole) to be available under a consistent > license, with the copyright transferred to a single entity -- > probably the FreeBSD Foundation. Where sections of the Handbook do > not do this, we will be contacting the original authors to ask them > whether they would consider relicensing their work. If they are not > happy for this to happen then we will need to replace the content > with text under a 'free-er' license. I don't see a problem with individual copyright holders as long as they're using a reasonable license. Their name in the copyright notice is also a form of credit; not everybody thinks it's appropriate to clutter the main text with "I rewrote this" type of attributions. > 8. Removing some content to other documents. > > As a minimum, we expect to move the following chapters and/or > sections > > Source Tree Guidelines and Policies -> Developer's Handbook > Kernel Debugging -> Developer's Handbook Perhaps now's a good time to bring this up: what exactly is the Developer's Handbook supposed to be? Right now, it seems it's a more advanced (read: more technical) version of the Handbook. This is good, but it contains three types of content: general programming information (e.g., sockets), FreeBSD-specific programming information (e.g., kernel API), and (soon? already?) general information for/about FreeBSD developers and/or the development process (e.g., source tree guidelines). It would be nice to break up it into those three sections, but at least the latter bits (info for/about FreeBSD developers) shouldn't be in it. Perhaps we can take that and the Committer's Guide and make it into The Big Book of the FreeBSD Community (please don't use that name, though!). > PC Hardware Compatability -> Book in its own right (?) This should probably be in the relnotes. > Bibliography -> Book in its own right (?) Erm, the bibliography should really stay with the document (book) that it goes along with. However, the Handbook's Bibliography section should be spelled Other Links. > 9. Adding additional content > > Chern Lee is working on a chapter for "Configuration and Tuning", > and Chris Shumway is working on extending the X11 chapter. Yes! This is exactly what we need more of. We have plenty of people doing the minor whitespace/spelling fixes, but we've been down on new or updated content lately (and I'm not helping :-/). And while WRS is sponsering this stuff, perhaps they can get another computer to act as www.freebsd.org; having freefall do that isn't good for security. Oh, and maybe they can help fix the "broken Handbook" problem that comes up every so often on the lists; it's quite real, and is happening more and more often now :-/. Regards, Dima Dorfman dima@unixfreak.org 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?20010710113247.A2B863E28>