Date: Mon, 12 Mar 2001 11:18:11 -0800 (PST) From: John Baldwin <jhb@FreeBSD.org> To: Chris Costello <chris@calldei.com> Cc: doc@FreeBSD.org, Udo Erdelhoff <ue@nathan.ruhr.de> Subject: Re: Translators: Need feedback on FAQ reorganization Message-ID: <XFMail.010312111811.jhb@FreeBSD.org> In-Reply-To: <20010311174633.F31751@holly.calldei.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 11-Mar-01 Chris Costello wrote: > On Monday, March 12, 2001, Udo Erdelhoff wrote: >> I've just downloaded the (rather old) snapshot of your work from your >> homepage at people.freebsd.org and I'll just that snapshot as the base >> for my comments. >> >> I've noticed a couple of things that worry me: >> >> 1) Most questions didn't have an SGML id. Please do not remove the >> ids, they are extremly valuable to point users into the right >> direction. > > I was going to work on re-adding those. However, I'm waiting > for feedback before I go do anything new to the new-FAQ. If you just start off moving bits around you won't be removing them. :) Then once bits are moved around, you can sync up the FAQ in the tree with your local content changes, and just not sync up the tag removals. >> 2) Please do not use the <name>/chapter.sgml structure of the handbook. >> make is perfectly capable of handling more than one source file in a >> directory. We don't need all those additional subdirectories and they >> make it easier to become lost in the sources. Imaging having 5 or 6 >> editor windows (or screens, in my case), all editing "chapter.sgml". > > Anybody else have any opinion on this? Nik? I was following > the Handbook's structure for the sake of continuity. Hmm, I like having multiple directories personally, but that's just me. Yay for consistency. :) For one thing, using directories allows us to group together the SGML source, images, etc. for one chapter all in once place, rather than having all the images and sources and makefiles, etc. all living in one directory. >> Check in the current version of the FAQ as Revision 1.1. >> >> Start moving the questions, one target a file at a time. In other words, >> if you create application.sgml, move all the questions about applicaitons >> into that file, add the neccessary SGML glue, and commit that change to >> your local repository. Do not rewrite the existing questions, do not add >> new questions. Just a simple move. > >> Repeat the process until you've redistributed all the existing questions >> to your satisfaction. >> >> Start adding the new questions and commit them one question at a time. >> This way, the translations teams can easily split the work. >> >> Now you can start editing/rewording questions. Group your changes into >> logical blocks, modify only one file at a time, and commit each block >> seperately. > > Sounds good to me. I'm still interested in what everybody > else thinks, too, though. But that sounds pretty logical. > >> [0] It might be possible to use the "our" repository (i.e. that of the >> FreeBSD German Documentation Project) for this purpose. I'll talk to >> Alexander Langer (alex@big.endidan.de) about it, it's his box. > > Not a problem. Either a separate branch for the FAQ[0] in the > FreeBSD CVS repo itself, or a separate repository on > usw4.FreeBSD.org (I already have an account) should also do just > nicely. Erm, we already have a CVS repo we can do this in. :) Very easily in fact. Just commit the changes one step at a time to the actual doc/ repo. No need to go off and obscure this in some side repo. As long as the FAQ builds, there is no need for a sidebranch, either. In fact, sidebranches are quite troublesome, as you have to merge all the changes back across once you are done. -- John Baldwin <jhb@FreeBSD.org> -- http://www.FreeBSD.org/~jhb/ PGP Key: http://www.baldwin.cx/~john/pgpkey.asc "Power Users Use the Power to Serve!" - http://www.FreeBSD.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?XFMail.010312111811.jhb>