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