Communications from DMN

Last week, I spoke at the Free Software Open Source Symposium (FSOSS) at Seneca College here in Toronto. It was an interesting experience, partly because this was the first Open Source event I’ve been to in quite a while, and the first time I’ve spoken to an audience of people involved in Open Source development and tech writing.

On top of that, my presentation was one of three back-to-back sessions on technical writing. I was in the middle of two very good talks. Here’s what was said.

The 4th dimension: documentation that enhances the user experience

First up was Beth Agnew, a long time technical writer and an instructor with Seneca College’s technical communication program. Interesting note about Beth: she got her start in tech writing in the military. A good place to learn the basics, she said. In the kinds of situations that they encounter, soldiers don’t have time to read long documents. They need to get to the point quickly.

Beth’s presentation was a solid overview of technical communication methods, and she explained how to apply those methods to documenting Open Source. While the tools used are different from those that most of use are used to using, the ways in which people document Open Source definitely aren’t. As you’ll see, they’re quite similar to the ways in which most of us write documentation in the corporate world.

She started off by outlining the Software Development Life Cycle (SDLC) and how documentation fit into it. And that’s at every point. Beth stressed that maintenance is a portion of the SDLC that’s often neglected, both for code and documentation.

But why documentation? I think we all know the answer to that … But the key points that Beth pointed out were:

• Nothing is completely intuitive
• Documentation can help lower support liabilities
• Documentation is a safety blanket for users, and helps create a better user experience
• By documenting code — even if it’s just comments in the source — you give potential contributors to an Open Source project better access to the code

But one key element of documentation (whether for Open Source or otherwise) is that it creates more information at all levels. Which can translate to fewer bugs. Documentation also encourages users, and encourages collaboration.

As you know, I carp on about the 5 Cs of documentation. Well, Beth added a sixth one: Considerate. Consider your audience, know your audience, keep your audience in mind when writing.

Another point that Beth stressed was collaboration. Not surprising, since FSOSS is an Open Source event, and the Open Source ecosystem thrives on collaboration. Of course, she discussed using wikis for documentation and looked at the pros and cons of using wikis for documentation. That said, Beth pointed out that the pros definitely outweighed the cons.

Documentation for Open Source projects is fluid, even more so than corporate documentation. It’s delivered in multiple formats — everything from PDFs to online help to man pages to wiki pages — and is constantly being updated. Beth pointed out that the documentation must have a strong user focus. Are you writing for one group or multiple groups? Sometimes, you need to develop documentation that spans the breadth of the user experience — from kids to Ph.D.s.

Beth also talked about a task focus vs. a feature focus. While developers like the latter, it’s the former that serves the user better. In the end, though, Open Source technical writers (like other tech writers) need to balance the documentation with the needs of users.

Some of the other information that Beth outlined included:

• The techniques for creating documentation, including how the documentation cycle mimics the development cycle
• The need to back up your documentation and, more importantly, making sure that you have a restore process that actually works.

Good documentation, she said, also involves adding documentation to the user interface — informative labels, tooltips, examples, and the like. And, of course, error messages that anyone can understand. That kind of documentation helps guide users and gives them both comfort and confidence.

Beth finished by saying that there are opportunities in the Open Source world for technical writers. You need to scour your community for writers (professional or otherwise), and the people with those skills can be a big help to an Open Source project.

And writing for an Open Source project can be the springboard to a full-time technical writing career. Beth pointed out a student she had last year who missed out on a co-op placement. Instead, the student scoured SourceForge, found a project that she was interested in, and offered her services to the project. That student wrote some great documentation, and used that experience in her portfolio. It helped her get a job after she graduated from Seneca’s tech comm program.

Fame, fortune, and technical writing

Dru Lavigne, a well-known author on Open Source topics and managing editor of Open Source Business Resource discussed just that. Well, not in that order. The thrust of her presentation was how someone who has a passion for writing can get involved in Open Source to further their career as a writer — technical or otherwise.

The core of the presentation is based on Dru’s own (very extensive) experience. But if you’re (as calls herself) a word geek, then you might just be able to mold a career that combines writing and Open Source. Dru pointed out that if you’re interested in writing (technical or otherwise), it’s a great time to take the plunge. The opportunities to get your work seen are there — there are no barriers to entry, and there are many ways to publish. But the main problems are how to 1) get noticed, and 2) get paid.

The key, she said, is community. The various misconceptions that applied to Open Source developers 10 years ago now apply to writers — writers don’t get paid to write about Open Source, and you’re nobody if you’re not a code jockey in an Open Source project. The latter is still true, and that situation definitely needs to change.

Dru pointed out that writing, even if it’s not being done as part of Open Source community, is a collaborative effort. It involves the writer, editors, and readers. But in the Open Source community, people who are good get noticed and, eventually, get paid. It takes time. Also, the community offers interaction, mentoring, and exposure. It also lets you explore what you want to write and how, while providing your with ample opportunities.

She said that there are several factors to take into account when trying to get started writing in the Open Source community. The main ones are:

Contributing – Pretty obvious, no? This could involve a personal introduction to the head of an Open Source project, or an offer to co-write and article or book with community members. It could also involve inviting people to join community, or sponsoring someone as t cover a conference.

Recognition – Obviously, to be successful you need to get your name out there. Especially if you want to snag professional assignments. Dru advised not to wait until your work is perfect to publish it on a blog or Web site. Get your work out there, but always try to do your best writing.

Focus on improving your grammar and spelling, whether in in blog posts, in posts to mailing lists, and even in email. Also, do research. If you don’t, it will show. Worse, it will bite you — there’s always someone ready to pounce.

Dru also advised people to write daily. If you hate writing daily, maybe writing isn’t for you. And there’s no degree or training required. You can cultivate the skills you need for writing. Just remember to write and be critical of your writing.

In the end, you want the work to find you and to get more offers than have time to tackle.

To gain an audience, and wider recognition, you need to write. Dru mentioned that a blog is a good vehicle for this. You need to to blog, to write book and/or software reviews, articles, and how-tos.

Inspiration – It’s out there. Look at your own interests, whether they’re:

• Curriculum development and training
• Writing marketing material or whitepapers or brochures
• Preparing news briefs
• Writing documentation or how-tos
• Doing editing

There isn’t an Open Source project that can’t use documentation in some form or another — man pages and guides, articles in mainstream publications, artwork, press releases, Web content, blogs, forum moderation/contribution. Give some or all of it a try.

Dru stresses that you should try writing something else or in another style. That will force you to learn to adapt and to write for that style. In the end, you become a more well-rounded writer.

Publishing – This is the big one. And it ties the other factors together.

If want to approach a publisher with a book proposal, you need to prove the size of the audience warrants the publisher devoting resources to a book. For better to for worse, most publishers are only interested in subjects that are currently popular.

Writing a book is a lot of work. Dru noted that in the world of technical books, a bestseller is about 10,000 copies sold. A typical book is about months worth of work, at 50+ hours per week; closer to 75 to 80 hours. And that’s considered fast. For new(er) writers, she advises that you to co-author first book, or write a few chapters of a book.

Overall, though, Writing a book is a roll of the dice. Especially since most books aren’t promoted properly. Dru suggests promoting your book beforehand on your blog or on a site like Twitter or identi.ca. Then, you need to promote the work aggressively just before or as book goes to print.

Dru also talked about rights — not just copyright, but also translation rights. If you can negotiate to keep the latter (most first-time authors won’t), then you might be able to get the community to translate the book into a language that a publisher might ignore.

Another interesting piece of advice she gave was to have your first book published by big-name publisher to get your name out there, then go with a smaller press or perhaps self publish. Self publishing can be the way to go if you’re dealing with a small niche or an esoteric topic. Again, you’ll have to aggressively promote the book and yourself on your blog and on one or more microblogging sites. But, Dru added, you need to sell enough copies to make make all that effort worthwhile.

What about earning? It’s definitely possible. Well, you should consider your goals and your priorities. Is writing a hobby, a career, or a means to an end? If you’re volunteering your time and your skilles while writing for money, you’ll need to regularly re-evaluate the ratio of the types of work you’re doing. If you reach the point where you’re getting more paying assignments than you have time to tackle, you probably need to scale back on your volunteer work.

Dru concluded her presentation with an interesting, and very valid statement: you need to define success as it applies to you. Do you want to make a little money on the side, make a living, or become what she called rock star? The big differentiator is the time you put in, and the dedication and passion that you have. You can harness that to mold a career.

Summing up

I learned quite a bit from the presentations that Beth Agnew and Dru Lavigne gave. Some of it was new information, but most of it was a good reminder of some things about the writing life that I’d … well, not forgotten but tended to ignore. And I ignored them when I shouldn’t have.

That alone was definitely worth the 110 minutes I gladly spent listening to those presentations.