A disadvantage of hotel wake-up calls is that they do not have a snooze button. If you start to snooze, they will not call you back in five minutes. As a consequence of this fact, I arrived late to breakfast, which was served at the lovely Ginger Press cafe, book shop and publishing house, run by Emma's mom. Mmm, pancakes and maple syrup!
After a chat with the mayor of Owen Sound, who dropped by the cafe to meet the conferees, we walked over to our meeting space at the public library, escorted by Charles the bagpiper, in Highland dress, updated by Keen sandals. I took pictures, but neglected to bring a card reader to get them off my camera.
Licensing for Authors
The first talk of the day was by Megan Langly Grainger, an intellectual property lawyer who prefers plain talk to legalese. She reviewed some basic concepts of copyrights, and gave an overview of some of the major licenses used for open source documentation.
- GFDL is intended for book-type works with few authors or revisions. It is not suited for massively collaborative works, because revision-tracking becomes very burdensome. It is also not compatible with GPL, CC-BY-SA, or CC-NC.
- Creative Commons is good for massively collaborative works, but is not suited for software.
- GPL is intended for software, not documentation (though FLOSS Manuals uses it for docs). Derivative works must use the same license, and must give access to the source.
- Dual-licensing is a way to deal with license incompatibilities. It can also be useful for market segregation. Be sure to think carefully about letting others use your work for their own commercial purposes.
One question that was asked was how to avoid infringing someone else's copyright on a procedure. There's only so many ways to succinctly say "Choose File > Open." Answer: Facts cannot be copyrighted. So, to the extent that content is factual, it is not copyright-able.
Megan also talked about publishing contracts, and especially non-compete clauses. Publishers often try to limit the other writing projects that authors can do while under contract. They don't want their authors undercutting them. However, they may not realize how related activities by authors can help promote their book sales. If you can, make sure the scope of the restriction is as small as possible, so that, for example, you can still do articles and presentations, and can write on related topics (such as new versions of the same software).
User-Centered Design for Modular Documentation
Lynda Chiotti, an information architect based in Owen Sound, talked about using user-centered design to produce modular, task-oriented documentation. These are best practices that professional tech writers generally know we should be doing, but don't always do. They are often lacking in open source doc projects, and unknown to non-professional volunteer writers.
Three factors for successful documentation:
- user-focused
- designed as modular, task-based
- planned development
Other notes:
- Using personas helps you visualize users, tell their stories, and determine your goals for their user experience.
- Do your own user testing, because "user testing will happen" whether you do it or not. Bad software and bad documentation each set user expectations for the other.
- Do guerilla testing using whoever you can rope into being subjects, to keep costs low.
- Ask for factual feedback to screen out opinions and emotions. Use a mix of open and closed questions to manage feedback.
- Tell testers you're not the designer "even if you have to lie". Otherwise either people try to please you or they get cranky.
- If you have existing content, put it aside, and design the document structure first. You can add in existing content later, if it fits.
- The granularity for topics should be what the user needs in order to do one thing at one time.
- To help you define tasks, try IBM Task Modeler, which is Eclipse-based and can output to DITA.
Fame, Fortune, and Technical Writing
After a yummy lunch of salad, split pea soup, and butter tarts, catered by Ginger Press, Dru Lavigne spoke on Fame, Fortune, and Technical Writing (in other words, getting paid to write books on open source software). Dru has a nice little acrostic for her topics; I didn't write all of it down, but it spelled out "I WRITE". One of her major points was that would-be authors need to be involved in the community for the project they want to write books about. You will need help from the community, and that only works if you are part of the community, helping both the project and other individuals. To hone your craft as a writer, write daily; it helps you build a body of work, define your style, and find out what you like to write about.
Things publishers like to see:
- the size of your audience
- that your expertise is currently "hot"
- the scope of your work (i.e., you've been writing for a while)
- a well thought-out book proposal
Learning Styles and Documentation
Belinda Lopez is an instructional designer who has worked with learners ranging from preschoolers to astronauts (at NASA) and now manages learning programs for Canonical Software. Her lively talk on learning styles included passing out koosh balls and colored pipe cleaners for the kinesthetic learners in the room. There will likely be more discussion on Day Two of how to address different learning styles through audio and video.
Cat-Herding 101
Addi Berry shared her experiences thus far organizing volunteers as documentation lead for Drupal, "not a voice of authority, maybe a voice of shared pain". She noted that being a doc lead is not much about writing, but is very much about community organizing, dealing with the diversity of humanity that is drawn to open source projects. She sees her role as:
- Banging the drum about documentation to get attention from people in the larger project.
- Helping the group develop a consensus about direction.
- Communicating that direction, so the "cats" don't just mill around.
- Empowering people to do whatever it is that they're passionate about.
- Letting go and getting out of the way.
- Building trust and relationships.
The last point is key — people will only do what you say if they trust you.
Finally, my day ended with a delicious dinner back at Ginger Press, and a walk back to my hotel.