On Mon, 9 Jan 2006 09:34:22 -0500 Aron Griffis <[EMAIL PROTECTED]> wrote:
> Brian Harring wrote: [Sun Jan 08 2006, 09:16:36PM EST] > > Regardless, (imo) it's already been laid out why guideXML'ifying > > everything doesn't totally work. Three reasons... > > > > A) bit of work required just to jot down a quick list of "this is > > broke, fix it" that's going to be thrown out 2 weeks down the line. > > I noticed Ciaran has been using RST for GLEP 42. I wonder if it would > be a good alternative to guideXML in general. > > http://docutils.sourceforge.net/rst.html > > I realize this doesn't address the *rest* of what you said, though... I agree. These little 'howtos' are potentially very short, and guideXML would be overkill. RST is absolutely perfect for this kind of thing: quick and easy to write, powerful, and legible in raw form. It's also easily converted to any number of other formats. A new CVS repository containing these little howtos that is accessible with viewcvs would be perfect, if you ask me. There would be proper version control on the files and they would be read/write for developers and read-only for users (otherwise the potential of vandalism etc. is too high). This is, in my opinion, how things should be for these simple developer guides. I'd also propose that these things are listed in a flat directory hierarchy, more or less. I'd rather the names of the files were prefixed with the project/herd name and then dumped in the same directory.It would encourage 'reading around' a bit (you know, like when you look up a word in a dictionary and end up learning another few words by accident). This can only be a good thing (I'll admit that, say, a documentation developer stumbling across the Gentoo/MIPS stabilisation criteria is not in reality that useful useful, but in the majority of cases this rule holds true). The whole wiki-for-everything idea really annoys me. It forces a web browser on me, and this is particularly naff when it comes to editing. It's also really bland and boring, and completely unoriginal. They're also hard to navigate. If I was going to write one of these guides I'd rather put a .txt on my devspace than bother with the devwiki. I still haven't fixed the other two points Brian mentioned, but I don't really think they're all that serious. If a user sees an omission, he can drop a mail to the guy who wrote the guide. There's really no reason to file bugs for anything like this. Allowing universal r/w is asking for vandalism. As for the third point -- concurrency -- this is exactly what any VCS is supposed to fix. We live with it with the tree's CVS, I'm sure we can live with it for this. I guess it's also important to distinguish what constitutes a little development 'howto' for some common task, rather than a full-on GDP guide. -- Tom Martin, http://dev.gentoo.org/~slarti AMD64, net-mail, shell-tools, vim, recruiters Gentoo Linux
signature.asc
Description: PGP signature
