Date: Wed, 5 May 1999 11:21:35 +1000 From: jonathan michaels <jon@caamora.com.au> To: nclayton@lehman.com Cc: freebsd-doc@freebsd.org Subject: Re: doc/<lang>/books/*, doc/<lang>/articles/*, and docs.freebsd.org Message-ID: <19990505112135.B3157@caamora.com.au> In-Reply-To: <19990504163533.S14492@lehman.com>; from nclayton@lehman.com on Tue, May 04, 1999 at 04:35:33PM %2B0100 References: <19990504163533.S14492@lehman.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, May 04, 1999 at 04:35:33PM +0100, nclayton@lehman.com wrote: > FDP folks, well, i'm an vested interest participant. > [ I'm sort of thinking out loud at the moment ] stuttering back .. > The doc/ directory structure is currently organised as > > doc/<lang>/handbook > doc/<lang>/FAQ > doc/<lang>/tutorials/* > > where <lang> is the appropriate language code (ignore doc/FAQ/* for the > time being, it's migrating soon-ish). > > In addition, there's a doc/share/mk and a doc/share/sgml for language > independent bits and pieces. > > I'm wondering whether it's worthwhile migrating the existing > content to a doc/<lang>/books/ and doc/<lang>/articles/ directory > structure instead? > > Specifically, I'm not happy about the FAQ and the Handbook being a > directory level higher than the other content. It's not 'clean', and > it means that any automated tools to process the documentation > have to consider either the FAQ and Handbook as special cases, or the > tutorials as a special case instead. regarding my recent ramblings into makefile mysteries, i was begngin to wonder aboutyhat. > This will get worse when I (and anyone else that wants to help) start > splitting the Handbook up into separate, smaller, books[1]. Where does > the new content go? > > I think this then allows for things like > > doc/<lang>/books/printing/* > doc/<lang>/books/security/* > doc/<lang>/books/FDP-primer/* > ... > doc/<lang>/articles/FAQ/* > doc/<lang>/articles/fonts/* > doc/<lang>/articles/ip-aliasing/* > ... > > and so on. sounds, er looks good to me > This sort of thing could be done as part of the DocBook conversion -- > instead of doing it in-place, the results of the conversion are placed in > the new directories, in the same way that doc/handbook/ was migrated to > doc/en/handbook/. > > This wouldn't happen overnight, and I'm not advocating changing the URLs > on the website. > > Yet. > > This brings me on to my second point. docs.freebsd.org. i think that this would be an advantage, if handled properly. > At the moment the FDP doc/ tree and the www/ tree sit a little uneasily > together. Building the website requires that the doc/ tree be available > as well, and in the process all sorts of symlinks are created and little > hacks exist in several Makefiles to get the build to work properly. > > It's all fairly fragile, and I'd be happier if it was a little more > separate. i was wondering why it was done the way it was from teh begining, i put it down to amerian ideosyncractic behaviour, no insult intended ... ummm, i'm getting to be overly 'sensative' today. > I think that in an ideal world we'd also have a doc/<lang>/www/ tree > which would contain *just* those pieces of infrastructure necessary to > support a docs.freebsd.org which had a front-end that listed the available > documentation, linked to it, and let the user search it. In the fullness > of time (once the technology's mature) it might support XML in some way > as well. yup, sure thing .. > For an idea of what I'm thinking of, take a look at http://docs.sun.com/. > Take their "Hardware" and "Software" headings and replace them with > "Books" and "Articles", and it's pretty close to the end product I have > in mind. the first time i went thier and saw what they did it made me wonder why we couldn't/didn't do it like that as well .. cncdering we were supposed t be as 'mature' as teh sun crowd. while i'm here .. have you looked at teh overal mess teh freebsd website really is. sun (from memory) asks if you want a text version and then gives the viewer a clean presentation. when i use lynx, the freebsd site is a vertitable nightmare to navigate, maybe a checkpoint could be inserted and teh user asked if a text version is required and a text version be supplied if requsted. maybe my yetagain whine will become irrelevant onc3 i get and start to use w3:amaya/toth combination .. but, lynx may still be the one if this new gui fails to meet exectations. this whole issue of organisation is a subset of teh broder problm od usability/readability. tackling teh one without the any referance t its kindred spirit will produce yet another ork. > Of course, we don't have to do either one of these. But to my mind, > docs.freebsd.org becomes that bit easier to create (and automate) if > the directory structure's a bit more rigid. as was pointed out to ne by one who claimed superiority, i'm no developer and hence have no skill in that bent .. but, i can see how it would be of importance and can also understand how, changes made for a more easy development cycle can help produce a better and more readable hence more usable documentaton set. > Of course, this does bring up some issues. Two immediately spring to > mind. > > The first is mirroring -- we already have many mirror sites who mirror > www.freebsd.org around the world. Would they be prepared to mirror > docs.freebsd.org as well? The only way to find out is to ask, which is > part of the reason for this message. open ended discussion is alway good, as long as it is discussion > The second is URLs changing -- in an ideal world, once you've published a > URL it stays the same forever, otherwise you get link rot. But you can > get around this by remapping URLs on the webserver, so that just an observation .. i thought it was teh web host maintainers responsability to check (ona timely basis) that the information on the site that they are maintaining, is correct, current and presented in an apropriate manner. while it is encumbant upon the originator of teh content to refrain from frivilios posturings .. from a moral or ethical responsability partnership type of relationship type of co-dependancy thingy sort of area od intersts .. well you know what i mean .. thingy. i suppose what i'm saying is that it is just as much the responsability of teh mirrors to make sure that the links are current and available as it is upon teh originator to make keep the links current and avalable. your arguement intones teh idea that the originator has sole responsability and a (over large) share of the workload in maintain teh visability of teh products 'world image', its availability and sustained(able) viability. > > www.freebsd.org/handbook/foo.html > > is automatically mapped to > > docs.freebsd.org/books/handbook/foo.html > > instead. > > Thoughts? a $AUD3.74 .. assuming i haven't been devalued, yet again. regards jonathan -- =============================================================================== Jonathan Michaels PO Box 144, Rosebery, NSW 1445 Australia ===========================================================<jon@caamora.com.au> 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?19990505112135.B3157>