Documenting the OpenDocument Format
An Interview with Jean Hollis WeberBy
We talk with Jean Hollis Weber, a volunteer with ODFAuthors, the LibreOffice Documentation team, and the Friends of OpenDocument Inc.
In many ways, ODFAuthors is an exception among free software projects. Its purpose is not to produce code, but documentation – chiefly user guides – for office programs that use the OpenDocument Format (ODF), such as LibreOffice and Apache OpenOffice. Moreover, instead of using version control, contributors mainly operate by the old-fashioned means of exchanging drafts. Yet, under the leadership of Jean Hollis Weber, a retired technical editor and consultant, ODFAuthors has become one of the few ongoing documentation projects in a community that has a history of neglecting help and user support.
Weber discovered OpenOffice.org, the first ODF office suite, in 2003. “At the time, I wasn’t really part of the OpenOffice.org project,” she says. “I was just fiddling around learning how to use the software. But there weren’t any books, and the help was kind of hopeless.”
She started taking notes, and “one day I looked at the pile of papers on my desk, and I said to myself, ‘You know what, I’ve written a book’.” With some rewriting, the book became Taming OpenOffice.org Writer, the first book specifically about the office suite’s word processor. Its success launched Weber’s career as an expert, which continues to this day
While Weber’s own career was evolving, she was also “taking part in the forums and so forth. I started looking at the documentation project, and there was a group of us who completely independently had come along and decided that the project tracking tool, which was Bugzilla, was really too hard for the volunteer writer to use. So in June 2004, a group set up a separate website, which they called OOoAuthors [OpenOffice.org Authors].”
At the time, OpenOffice.org was owned by Sun MicroSystems, which kept tight control of development. According to Weber, OOoAuthors was condemned almost immediately as “an outside project.” In particular, its founder, Daniel Carrera Yanes “was vilified by some people for having had the audacity to do this.”
Weber received something of the same treatment when she and her partner founded Friends of OpenDocument, an Australian non-profit that published user guides. Friends of OpenDocument was pressured to donate its profits to OpenOffice.org but refused because there was no public accounting of how the project used donations.
“If it was there, it was well-hidden,” Weber says. “That was the reason why we didn’t want to give them any money, because we didn’t know how it would be used.” The result was that,”We considered ourselves part of the OpenOffice.org community, but some people didn’t.”
The animosity continued for several years, until Frank Peters and Clayton Cornell became the documentation leads at OpenOffice.org. Because they focused chiefly on developer documentation, they were able to view OOoAuthors and Friends of OpenDocument as something other than rivals. When Weber replaced Peters at the end of 2008, “we considered ourselves vindicated,” Weber says.
Further potential problems arose when OpenOffice.org was acquired by Oracle and later donated to The Apache Foundation. For about a year, “Very little was being done with documentation because very little was being done with the project. So a lot of people left, and those who were still around went over to LibreOffice when it turned up, because at least something was happening there.”
Considering the animosity among developers at LibreOffice and Apache OpenOffice, the project might easily have faced similar divisions – particularly Weber herself, who switched from Documentation Lead in OpenOffice to the same position at LibreOffice; instead, the project changed its name to ODFAuthors, which now hosts projects for both LibreOffice and Apache OpenOffice in several languages.
So far, the site hosts nothing about Calligra Suite, the other major ODF office application, but Weber stresses that, “if people from Calligra would like to use our site for storage, we’d be delighted.”
She notes that some people still don’t understand the relation of ODFAuthors to LibreOffice and Apache OpenOffice, but immediately adds, “I guess the take-away from that is that it doesn’t really matter. What we’re doing seems to be working.”
Formulas for Success
Why has ODFAuthors thrived when so many development projects continue to struggle to provide even rudimentary documentation? Weber suggests that one reason is because ODFAuthors is about programs that “ordinary people use. The audience is quite different from a lot of other open source projects, particularly when it started; they all seemed to be really geeky stuff. I know that I got into it simply because I used the program and needed better documentation. I suspect that others did, too. So we had to do it ourselves.”
Another reason may be that the project has always kept its goals well-focused. Weber laughs when she says, “I have no objection to other formats, but I’m book-oriented, I’m sorry. I’m too old for video or that other stuff,” but concentrating on print has the advantage of ensuring that the project’s efforts never become too diffuse.
It helps, too, that ODFAuthors has a tradition of using the applications it is writing about. “We’ve had all these debates over the years about what to use. Some people say, ‘Oh, we should use DocBook’. But I say, ‘No, no, you’ve got to eat your own dog food’. You are documenting something that can go all the way to PDF and be printed as real books, so you use it as a demonstration. Any flaw that comes out is not due to the software, but the volunteer’s ability to use it.” In other words, the documentation itself becomes proof of the usefulness of its subject matter.
Still another reason appears to be Weber’s own combination of experience and leadership style. “It’s more leadership than management in my terminology,” she says, “although my unofficial title is ‘She Who Must Be Obeyed’ – a reference to both John Mortimer’s Rumpole series and H. Rider Haggard’s novel She. By that, she means that “everyone is a volunteer. So you can persuade them, but you can’t tell them what to do. You can’t say, ‘Well, here’s the deadline and we’re going to make it if you have to work overtime’, because it doesn’t work that way. And I prefer that, myself.”
In general, Weber says, policies just “sort of evolved. We just sort of muddle along. One thing I should do as team leader is spend some more organizational time, helping people get started, and writing the contributors’ guide and keeping it up to date. But I don’t enjoy that nearly as much, so I tend to not do it. Everyone talks about community-building, but I decided that it isn’t really my thing. I just want to sit at my computer and write books.”
Somewhat to Weber’s surprise, this attitude seems to work. “Because I don’t get around to it, competent people actually step forth and do things. And the first few times it happened, I was absolutely delighted and surprised. Now, I think that’s fabulous. I mean, as a group, we’re all supposed to be equal.”
The main problem is finding experienced people who can keep up with the work. The few professionals in the project like Weber are “used to writing from notes taken in developers’ meetings and specs, and used to writing stuff knowing that the details will change but the concepts will stay the same.”
However, others, although eager to help, are unable to write until the first release candidates of the software are available. Consequently, ODFAuthors frequently has trouble keeping up with the software releases. Weber is currently considering skipping releases in order to stay relative currently, although “it all depends on the people we have working and how good they are.”
All the same, ODFAuthors has managed to establish itself as the main source of documentation within its chosen fields, with its manuals being carried in places such as the software project sites and the Ubuntu Software Centre. Besides free downloads, the project sells an average of about 40 hard-copy editions of its manuals a month. “I try to price them to make a little profit,” Weber says, “but not a lot, because the point isn’t to make money – the point is to get the information out there.”
Traditionally, ODFAuthors is more of a development site for working volunteers than a site for distributing manuals. However, Weber is open to the idea of the site becoming a general repository for videos and tutorials on ODF applications.
However, noting that most of ODFAuthors’ material is aimed at new users, Weber says that “what I really want to do is write more stuff targeted to special audiences, such as academics or business people, or tech-writers for that matter – people who will be using features beyond the basics.”
Her latest book, the just-released Self-Publishing using LibreOffice Writer, can be seen as a first step toward producing this advanced material.
“I wrote it,” Weber says, “because I have a lot of friends who are science fiction and fantasy writers. Of course, many of them are self-publishing in addition to or in place of being published by others, and they all say, ‘Ohhh, I can’t afford Adobe InDesign’. And I tell them, ‘You don’t need bloody InDesign to do a novel’.”
Clearly, for Weber, ODF documentation has become a full-time job in her retirement. “You know what they say: The way you decide what you are going to do with your life is to ask yourself what you would do if you weren’t being paid. Every now and again, I say I’ve had enough of this and I go away, but within six months I’m back doing it again. So, obviously, I’m hooked.”
New tool will look like GParted but support a wider range of storage technologies.
New public key pinning feature will help prevent man-in-the-middle attacks.
Carnegie Mellon researchers say 3 million pages could fall down the phishing hole in the next year.
The US government rolls new best-practice rules for protecting SSH.
Klaus Knopper announces the latest version of his iconic Live Linux system.
All websites that use these popular CMS tools could be vulnerable to denial of service attacks if users don't install the updates.
According to a report, many potential victims of the Heartbleed attack have patched their systems, but few have cleaned up the crime scene to protect themselves from the effects of a previous intrusion.
DARPA and NICTA release the code for the ultra-secure microkernel system used in aerial drones.
Should you trust an online service to store your online passwords?
New B+ board lets you build cool things without the complication of a powered USB hub.