Documentation is a journey: 3 lessons learned from documenting Scribus

I'd like to use my own personal journey with open source documentation to illustrate how it's possible to begin with little to nothing and create—and then build on—your work and that of others.

The project I have been involved with is Scribus, a desktop publishing (DTP) application used to create PDFs for publishing in print or web pages. When I began contributing to the project some 10 years ago, I had no knowledge about it at all, and consequently spent some time reading and interacting with the mail list to develop an understanding of how to use it. Starting out, I asked quite a number of dumb or clueless questions, leading to more intelligent ones, and, after a time, I knew enough to answer other people's questions.

With a mailing list's steady influx of new users, it's easy to see that the same or similar questions are asked over and over. It seemed like we—already I was starting to feel a part of this project—could be making these expected questions and their answers available somewhere. The result was to create a Wiki, set up for users to make documentation for other users. At first the Wiki was created as an unofficial source of information, but with time it developed a reputation for having solid, practical information that users wanted. For me, the Wiki became a test bed for practicing writing documentation, incorporating images to enhance the text, and most importantly, learning more about Scribus. Just like most Wikis, the Scribus Wiki lets us write our own pages and edit and add to others' to improve the experience for users. Much of the inspiration then and now comes from the mail list, either by starting a new page or bringing an old one up to date whenever we see that users are not able to find what they need.

Around 2008, we noticed recurring questions about whether there was documentation someone could hold in their hands—in other words, a real book. After I took an initial sophomoric stab at beginning one, Christoph Schäfer jumped in and helped organize a real effort to make something more organized and sensible. The result, some nine months later, was Scribus, The Official Manual, a 400+ page manual written for the 1.3.3.x versions of Scribus. The work was initially done in a special section of the Wiki, then exported to OpenOffice so that styles could be applied, then exported into Scribus for the final layout. (We considered that it would have been sacrilegious to use some other DTP software to create the Scribus manual.)

Since then, using the manual as the inspiration, we continue work on revising and updating the online manual that comes with Scribus, so the work is never done with an actively developing project. This has indeed been an amazing journey for me.

Lessons learned

Here are some key lessons that I would like to emphasize for those writing documentation:

1. Know your subject: You can't adequately write about software unless you know how to use it, and not just in some trivial way. Not only do you need to do your own work on this, but you need to listen to other users, especially those who are proficient with the software. You will need to interact with the developers, particularly when new features are added. Likewise, you will have the opportunity to report bugs or make suggestions for modifications or new features.
2. Good writing takes practice: In my case, the practice started out with trying to explain answers on the mail list, then creating more generic responses for the Wiki. Along the way, you get feedback about whether what you're writing makes sense, whether it's concise, and hopefully that it's interesting to the reader. You have a chance to—and should—develop your own style of writing. This was one of the big chores that Christoph and I had with the official manual, trying to maintain a fairly consistent style throughout the book. And you also have the challenge of keeping it lively as you get to hundreds of pages. It doesn't hurt to read about writing for writing's sake so that you can become a better editor of your own work and that of others. Good writing is good writing, wherever you see it.
3. There is a richness that comes from working with others: I don't know if I could have had the energy on my own to accomplish what I have without the help of others. Additionally, the work I do is better because of their ideas and the feedback I received along the way. I have had the joy of seeing some of my better Wiki pages translated to other languages, one of the best compliments you can get.

Visit the Scribus site to learn more about the project and to see the online documentation, and don't forget about the manual inside Scribus.