Date: Mon, 24 May 1999 10:02:36 +0100 From: nclayton@lehman.com To: Greg Black <gjb-freebsd@gba.oz.au>, Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: doc@FreeBSD.ORG, freebsd-translate@ngo.org.uk Subject: Re: FDP Directory Reorganisation Message-ID: <19990524100236.V12185@lehman.com> In-Reply-To: <19990523023158.105.qmail@alice.gba.oz.au>; from Greg Black on Sun, May 23, 1999 at 12:31:58PM %2B1000 References: <19990513211458.B70767@catkin.nothing-going-on.org> <19990519214022.D60921@catkin.nothing-going-on.org> <19990520095342.18541.qmail@alice.gba.oz.au> <19990520232510.A54603@catkin.nothing-going-on.org> <19990523023158.105.qmail@alice.gba.oz.au>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, May 23, 1999 at 12:31:58PM +1000, Greg Black wrote: > [Re "articles" and "books":] > > An alternative way of expressing this, without getting in to the SGML, > > is that if it has more than one chapter then it's a book, otherwise it's > > an article. > > This is a semantic distinction based on something that is > utterly irrelevant to any /user/ of the documentation. Agree. 100%. > If the > object of the documentation is to provide help to the users of > the documentation, then the organisation needs to based on > distinctions that make sense to those users. Disagree. Here's why. The organisation *within the repository* is (or should be) of zero interest to the end user of the documentation. There's no reason why the directory hierarchy within the repository, and the directory hierarchy of the installed documentation should map to each other one to one. Categorising things is a hard problem. Take a look at http://www.freebsddiary.com/freebsd/topics.htm for example. Notice how many entries are duplicated under different headings? The IP Filter and Firewall sections, for example. I think trying to categorise based on content within the repository is ultimately futile. There will be cases where there is no clear category for a document to go in. So do you create a new category for this document? Lump it in a "misc" category with some other documents? Misfile it? None of these are good solutions. However, as I say above, I agree with you that a distinction based on SGML element choices is of no interest to the end user. Fortunately, we don't need to make this distinction when we install the documentation. There's no reason why the Makefile that installs each piece of documentation can't have a ${CATEGORIES} variable (or some other appropriate name) that lists the categories of documentation that this document falls into. For example, something that lives in the books/printing directory might have CATEGORIES= books sysadmin printing mswindows in the Makefile, indicating that the formatted documentation should be installed in to /usr/local/share/doc/FDP/{books,sysadmin,printing,mswindows} directories because 1. It's a "book" 2. Printing is a "Sys Admin" topic. 3. Printing is deemed to be important enough to have it's own top level category as well. 4. It explains how Windows hosts can print to printers attached to FreeBSD boxes. This gives the end-user much more freedom when it comes to finding the documentation they need. The installed docs can be copies, or links as necessary, but that's really an implementation issue. The actual categories to be used (or at least a first cut at them) can be decided relatively easily on this list. More importantly, the list of categories can be easily expanded to accommodate new documentation without any of the problems I outline above. In the meantime, back in the repository, we still need to separate out the manual pages from everything else. The books/articles distinction is completely mechanical (there's no discussion about whether something is a book or an article, it's a simple decision) and makes it a little bit easier for people writing new documentation to find example of a particular type of documentation that they can crib from. I'm happy with another distinction between the documentation sets, as long as it can be applied mechanically (i.e., no wondering about which category the documentation goes in to) and fits in with the existing man/ directory. man/articles/books fits that. There's a simple progression in the documentation detail from left to right, and deciding which directory to put the docs in is trivial. doc/ or docs/ doesn't. Manual pages are also "docs". N -- --+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+-- --+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+-- --+==[ Year 2000 Testing: It's about time. . . ]==+-- 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?19990524100236.V12185>