Last weekend, I attended the first ever Writing Open Source conference. With me were Milo Casagrande, Phil Bull, and Paul Cutler. Those guys have already blogged about the event. You should read what they had to say. Besides the four of us, there were twelve other attendees from various open source documentation teams. It’s amazing how many experiences we have in common.
On the first day, the mayor of Owen Sound came to visit us. She’s going to be participating in the Dancing For Life charity event this weekend. People were trying to get me to give her a waltz lesson, but it’s hard to give a dance lesson without a dance floor. (Plus, waltz is really not my dance.) In retrospect, I probably could have given her a connection lesson.
We all learned a lot. For the last two months or so, I’ve been keeping a notebook about documentation. Basically, it’s a brain dump of things I would tell somebody if I were to sit them down and teach them everything I know about building documentation within a community. After three days, my notebook doubled in size.
I got to show off Pulse and Mallard. Pulse was really well-received. It seems a lot of teams are looking for better ways to track their documentation. I get really excited about Pulse, so it was nice to get others excited as well.
There were a lot of DITA enthusiasts at the conference. Mallard and DITA occupy similar niches: They’re both moving away from DocBook-style books and towards topic-based documentation. The first question (which I expected) after I presented Mallard was along the lines of “Why aren’t you using DITA?”
The obvious advantage of using DITA is that it has a fair amount of industry uptake already. In my defense, I first conceived of Mallard back in 2004. At that time, I hadn’t even heard of DITA, and I don’t think it had nearly the popularity that it now has.
I have been trying to play with DITA since coming back. So far, I’m finding it has a serious lack of hands-on introductory material. As much of a bear as DocBook is, I was able to write my first document after 15 minutes with The Definitive Guide. After two days, I’m still wading through conceptual overviews in DITA.
Mallard is designed to solve a concrete set of problems. DITA can do a lot of things that Mallard can’t, but I’m not at all convinced that I should care about those things. I mean, DocBook can do a lot of things Mallard can’t as well, but after eight years, I’ve learned that most of things just don’t matter to us.
What DITA doesn’t do is what I consider Mallard’s single biggest selling point: dynamic organizational structures. This is critical to our strategy for downstream documentation. It also can produce some nice results for plugin-heavy applications. In fact, one of my primary use cases when designing Mallard was to make something that would work for the GIMP help.
We could probably build dynamic organization on top of DITA, but I’m not convinced it’s worth the effort. Besides capitalizing on uptake elsewhere, I have yet to see any concrete benefits to using DITA. I’m just not sold, and I don’t buy into the notion that I should be automatically sold just because others think it’s cool.
That said, I think we could have reasonably decent two-way conversions between DITA and Mallard. DITA people don’t generally seem to view DITA as a delivery format. So if people want to use DITA as an authoring format and Mallard as a delivery format, I don’t see any reason to put stop energy on that.
So I’ve been trying to learn DITA well enough to make those conversions. Documentation tool chains is what I do, both in Gnome and for a living for the next three days. And I have to say, I haven’t had an easy time of it. And that concerns me particularly because if I have a hard time, I can’t begin to imagine how tortuous it will be to any potential new contributors that come our way.
To their credit, quite a few of the DITA enthusiasts have offered help. They are a friendly bunch. We’ll see how things play out.
♫NP: Bongo Fiesta by Machito & His Afro Cuban Orchestra
Mallard does do some pretty cool things, and I love how (1) the markup is simple, (2) new content can be included in the overall structure on the fly, and (3) it has recursive (? not sure if that’s the right word) linking.
To me, DITA’s structure reflects where it came from, IBM. Documentors at IBM have a different set of issues than documentors at GNOME (or Fedora or Ubuntu or Debian or OpenSUSE, for that matter). People at IBM are paid to be smart and paid to deal with a crapload of sysadmin-esque documentation. GNOME documentors generally aren’t paid, and, in most cases, they don’t have a technical writing background. As I’ve seen it so far, Mallard seems to strike a balance between a reasonably simple syntax for non-techies to get a hold of, and a reasonable amount of xml-derived power and flexibility.
If people need the industrial-strength stuff, they could go to DITA for the big projects and really heavy lifting. And while I’m still keen to learn more about DITA, I don’t see why the two projects can’t coexist and serve their own purposes.
Jim, that pretty much echoes my thoughts. I don’t actively set out to reinvent wheels, but in this case I think Mallard will serve the needs of the Gnome community better. That said, I think there’s a lot of room for interoperability, and that’s something I’m interested in exploring.
And I tend to use the words “symmetric” and “reflexive” when talking about the linking structure. But I’m a mathematician, so I’m weird.