On Thu, May 08, 2008 at 11:39:10AM -0500, Luke Kanies wrote: > James kind of left out his motivations for thinking about this in the > first place, so I'll mention a few shortcomings that Trac currently > has. I think James is a bit more cognizant of those shortcomings, > though, because he's been spending a *lot* more time maintaining the > wiki than I have (it's worth looking through a Timeline on the wiki > and being amazed at how much time James has spent on it).
Excellent, this is what I was looking for. I have a bit of experience with Trac and MoinMoin so I might have valuable input here. > Wiki issues: > > It has no structure on its own. We as a community can attempt to > enforce structure, but it's always going to be a fight between the > cruft that develops over time and the structure we want. This is basically the nature of the wiki world in my opinion, although Trac's wiki is a bit weaker than others in that regard. I think Puppet's trac wiki is one of the better organised out there, to give you an idea. :) But I think you'll have the same issue with any wiki out there. If you want to build formal documentation and have the manpower to do it, docbook and friends are the way to go, IMO. Drupal's book module could help a lot here, especially since Trac's wiki already requires login to edit. > It also doesn't support multiple form factors -- if you want the > content of the wiki in a PDF, you're pretty stuck. I don't know of any wiki that does this properly either. MoinMoin has PDF output plugins, but they're per-page, as far as I know, so that won't help. Again, if you want to have a really well organised manual, more like a boot, a wiki is not a proper tool, at least not for the final organisation. http://moinmo.in/ActionMarket/PdfAction Maybe you could hack a Drupal module to have such exports from the book module, however, heck maybe someone already did that, considering how much work is put in contrib modules over there.. > One thing I'd love to see change is the wiki docs stored in a db > instead of in a version control system; using an SCM instead of a db > automatically gives you multiple interfaces for accessing the data, > and also makes it easy to write tools that validate or munge that data > (e.g., extracting it into a PDF). You won't get that with MoinMoin either. MoinMoin is still stuck with a flat-file custom version control system. Drupal *could* help here, since it's backed by a mysql database. > Bug tracker issues: > > The bug tracker isn't that great, I must say. I, on the contrary, think that Trac is one of the best trackers out there. :) > I'd tend to have tons of milestones, but Trac keeps all milestones > around, even if they're closed, so in a year we're going to have 30 > milestones, only two of which are valid. Well, you can delete milestones, and closed milestones are hidden by default... > Also, there's no way to talk about relationships between tickets. I > don't want a Gantt chart or anything, but being able to clearly mark > that tickets are related would be pretty useful. I admit this is a weak point. I usually just write down the ticket number in a comment and that makes a defacto link, but it would be nice to see blockers and relationships better... Mantis does this very well, by the way, but it sucks (or used to suck, I haven't used it in a while) at milestone tracking... > Basically, the bug tracker is ok for tracking issues, but it's crap as > a means of deciding what to develop. I know the ticket db pretty > well, but I'm still often surprised by its actual contents and how > tickets are related (my recent reorganization around components has > helped that some). I'd love a db that made it obvious where people > could have the biggest impact on development -- are there tickets that > are keeping us from fixing lots of other tickets? I guess you're supposed to mark those as blocking manually. ;) > Essentially, I think trac is fine for smaller projects, but Puppet is > mid-transition to a larger project, and I think we need our tools to > scale with us. > > A note on markup formats: > > Steven Jenkins encouraged the use of MediaWiki, but one of my primary > requirements of any choice is that we don't pick a format that's not > at least pretty close to a standard. MediaWiki's format is pretty ad- > hoc, and no one but MediaWiki uses it. There aren't external parsers, > I can't easily convert it to a PDF, etc. That's not exactly true: there are external parsers. MoinMoin has one for example, and I think there's a Drupal module for it too. So basically, there are already PHP and Python parsers out there. Not that I particularly like that syntax... > This is the same problem I have with the Trac markup, which is why I > stick to RST. I agree rst is a very good choice. > The docs are now in at least their third iteration since the start of > the project, and each iteration has been somewhat painful if non- > standard formats were involved. If we stick to RST, it's easy. > > I'd consider something like markdown or textile, but... they're > basically crap formats. Really. Markdown is actually close to RST, but it's much less clean... > One of these days I'm going to hack up my own rst2html parser in Ruby, > or maybe pay someone to do it. That would solve a lot of my problems, > I think. Hehehe... maybe someone already did it too. :) From what I can see, the main problem you're seeing now is the structure. In my opinion, this is more related to the Wiki paradigm than to the engine itself, so I would refrain from switching engines until that question is clearly discussed and resolved. Do we have the people to maintain a parallel "book" version of the ad-hoc documentation? A. -- If Christ were here there is one thing he would not be -- a Christian. - Mark Twain
signature.asc
Description: Digital signature
