Monthly Archives: September 2009

Choosing a license for sharing documentation content

I received this set of questions from Laura Ferrar after a Central Texas DITA User Group meeting this summer, and I have been thinking about these for a few months. These are good questions. I’ll try to answer them to the best of my knowledge, but I do think I should lead with the disclaimer “I am not a lawyer.”

Laura: Could you elaborate more on the legal and copyright issues of open source content, and collaborative content, beyond asking for permission?

Anne: First, a few definitions. Copyright was intended to protect the creator from publishers publishing the content, “to the Ruin of them and their Families.” That ruination quote is  pulled from the Statute of Anne, considered the origin of all copyright. Copyright was a concept written into the US constitution. Mark Twain thought it was a good idea to extend his copyright privileges in 1906.

Copyright law’s international standardization started in 1886. Copyright law gives the original creator exclusive rights to do with the content as they please. A writer might give someone one-time printing rights for an article or essay. A photographer might display a photo on Flickr but mark it with a certain license that indicates how you can use it.

Licensing the content is one of the things the copyright holder can do with the content to indicate how they, the creator, give permission for it to be used, sold, distributed, and so forth.

The phrase “open source content” isn’t precisely defined. The term open source typically describes software, but more and more people are using the term “open source” to talk about content that can be re-used as long as licensing requirements are met. Collaborative content could be created by a small set of trusted collaborators, and there are different production and sharing models you can follow for collaborative content such as wikis. My book, Conversation and Community: The Social Web for Documentation, goes into some ideas.

Laura: What issues and legalities do we as Technical Communicators or Wiki Administrators need to be aware of as we move towards collaborative authoring projects and so forth, especially when documenting open source software?

Anne: Projects that are open source give away the code artifacts to create the software. Open source software, as defined on Wikipedia, has many criteria it must meet in its licensing agreements.

Documentation specifically may lean towards an openess, but restrictions on use, requirements for attributions, and what happens with changes (or branches) from an original document source may vary widely. Legally, documentation writers should understand the license under which the content can be used, and follow the licensing instructions.

Creative Commons has four licenses that are explained in straightforward language on their website. The most accommodating requires only attribution. Then there are more restrictive mixes and matches that enable different commercial uses,  whether you must share any derivatives, whether you can make a derivative, and so on.

Licensing of content is something that we’ve talked about recently on the FLOSS Manuals discuss email list. Adam Hyde, the founder of FLOSS Manuals, also wrote an essay about free documentation and he is passionate in his thinking that even requiring attribution limits the “freedom” of content to go anywhere and be used by anyone. Collaborative content often requires that attribution of all collaborators be displayed somewhere.

Laura: How about content that is done collaboratively? How does that content get vetted, in terms of technical accuracy to avoid any legal liabilities?

Anne: I believe we create collaborative content quite often in a corporate environment, and your review process is how the content gets vetted. In larger collaborative environments, such as the ones that large wikis can scale to, there are more reviewers of the content. I believe the content is vetted if the company backs it up based on the language in the software contracts that happen at the sale of the software. In open source projects, the “contract” you enter with a provider may or may not exist. It may be “use at your own risk” or it may be “we are service providers for this open source software and here’s what you can expect from us.” The same general principles can be upheld for guaranteeing the accuracy of documentation. The legal liability lands in the contract that a person enters with the vendor of the software, I believe. Since I’m not a lawyer, I can’t guarantee avoidance of legal liabilities, though.

One model to follow is to offer two sets of collaborative content. One set of collaborative content has a disclaimer stating that the company or organization does not guarantee the accuracy of the content, such as “Content in this collection has not been verified by our company. Use all of the information here at your own risk.” Another set of collaborative content where the collaborators are only your company’s information developers, and their job is to provide content that is as accurate as possible. That collection of content would not need a disclaimer and could be displayed like an online help site. Lisa Dyer has an article on the WritersUA website that describes this model for company-generated content and community-generated content.

To learn more, you may want to watch these free training courses from this blog entry.

  1. Online Media Law: The Basics for Bloggers and Other Online Publishers: With this course, you’ll learn about copyright, privacy, defamation, and more for online publishing. [News University]
  2. Introduction to Copyright Law: Check out this course to get a lowdown on the basics of copyright law, specifically online. [MIT]
  3. A Fair(y) Use Tale: Here you’ll learn about fair use and copyright. [Novell]

Updated to add: Technical Communication student and Austinite Emmelyn Wang just recommended the book, A Legal Primer for for the Digital Age, which is in the Allyn and Bacon Technical Communication Series. Thanks Emmelyn!


Corporate collaborative authoring

At FLOSS Manuals, we have been using a method called a Book Sprint –  collaborative authoring, one week at a time. In fact, Google’s “Summer  of Code” project has sponsored two of these sprints. The latest was  just this month for a completely open source video format called Ogg Theora. The sprint got a mention on slashdot last month.

The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well. I like to think of it as using two wiki patterns – the Scaffold pattern first followed closely by the Barnraising pattern.

I often get questions about the viability and value of a book sprint in a corporate environment. Here are a couple of ideas for running a book sprint at a company.

Agile software development

In an Agile environment, the term “sprint” means a timeboxed iteration – a time period could be two weeks, or it could be three or four. You plan out the “sprint” based on the number of people you have and by correctly sizing the documentation goals for the sprint.

The term Book Sprint seems appropriate in an Agile environment. For example, plan the sprint to have the team focus entirely on doc for that iteration. That’s one company-type application.

Scenario-based documentation by Subject Matter Experts

Another company method of focused authoring that I know of is the one that IBM employs to write Red Books. A document coordinator brings in  the subject matter experts, they outline the RedBook in a day, then assign chapters to each Subject Matter Expert (SME). The SMEs usually go off and write for a while, then the RedBook comes back together with the document coordinator (I think this is accurate, but please do feel free to offer more detail by commenting).

Chris Almond gave a presentation at Central Texas DITA User Group meeting last year about using wikis for RedBook authoring – his slideshow is available on

Writer’s luxury accomodations – seclusion and focus with collaboration

For Book Sprints, what we do is try to get a good group of people a great place to stay for a week and write. There’s at least 4-6 weeks  of pre-planning of the outline and possible content that already exists so that the sprint itself goes smoothly. Getting people to agree to audience and scope ahead of time is crucial. A book sprint  basically forces documentation decisions and priorities under pressure of one week’s time – so you want to get lots of questions out of the way before the actual sprint.

We also make them fun and offer food and “after hours” activities. The fun is crucial!

I just joined the Writer’s League of  Texas, and they actually charge people for writing retreats that sound  an awful lot like a book sprint, except that they’re not collaborative, they’re for solo writers to get writing done in a nice, supportive environment. It’s basically a nice location with some fun planned in as well.

We have case studies and lots of planning in a Book Sprint book hosted on FLOSS Manuals at Also,  the free sample chapter from my book talks about Book Sprints at length, see, and shows how much funding we needed for a book sprint last August that produced about 300 pages of printed PDFs and online HTML-based help.

Tragedy of the commons

Are professional associations going the way of bowling leagues? I don’t think so. And I certainly hope not since my employer, ASI, provides software for non-profits which includes professional associations.

But it is certainly an interesting premise that there are fewer mechanisms for casual introductions because of a shared activity like bowling or bridge. Robert Putnam wrote an article in 2000 called “Bowling Alone” that turned into this book, Bowling Alone : The Collapse and Revival of American Community. It’s a fascinating premise and I’d like to read more just based on this quote, “Our growing social-capital deficit threatens educational performance, safe neighborhoods, equitable tax collection, democratic responsiveness, everyday honesty, and even our health and happiness.”


Technology – part of the solution?

If you’ve read my book, Conversation and Community, you might think I’d advocate for online activities like Scrabulous (now Lexulous) for casual introductions and getting to know people. And there are certainly stories where Twitter has introduced people to each other in new ways, such as Michael Hughes discovering common interests with others unexepctedly through Twitter and Facebook  interactions. In his post, Social Web: This old dog finally gets it, he says:

As an officer, I’ve taken quite a bit of heat over some unpopular decisions and problems lately from well-meaning and articulate critics. Twitter and Facebook have given me the opportunity to interface with some of these critics at the level of home-brewed beer and love of musical instruments.

A strong personal touch

Yet, there are some technologies that can make group work more difficult. As Clay Shirky eloquently explains in “Group as User: Flaming and the Design of Social Software,” mailing lists can have the most difficulty with signal-to-noise ratio. You know you’ve seen it happen on lists over and over again. Someone writes something that everyone needs to respond to, and then the responses don’t add to the original discussion. Even the best-behaved list members have difficulty obeying rules of conduct set forth. Naturally, the problem is more difficult when the list is large, because people who crave the “upset” attention will get more drama on a larger list.

On the other hand, blogs and wikis have built-in rules of engagement that assist with this problem. Clay Shirky outlines many assistant design decisions in the essay referenced above. But you still have to be willing to moderate comments when you are a blogger or a wiki administrator. And you have to be willing to work hard to build a community that uses the technology in a productive way.

Talking to Ellis Pratt about Conversation and Community

I spoke with Ellis Pratt with Cherryleaf in London from my home in Austin for a video interview last week, and the shortened version is available online now.


He had many good questions, ones that I enjoy discussing all the time, such as the future of our profession. One good one was “What will user documentation look like in the future?” Also, “Is there too much reliance on search?” and “What are the blind alleys?”

I’m not sure I have all the answers, but I do enjoy talking to people who “get” it like Ellis does.

Here’s a direct link to the interview, which has slides guiding you through highlights of the the questions and answers.

I really appreciated Ellis Pratt and Cherryleaf giving me the opportunity to talk about the concepts in my book. These types of interviews – video, audio, lunchtime, you name it! – lend more dimension to the book than just flat pages. I appreciate it!

Advanced wiki techniques – collaboration in authoring

Today I gave a presentation remotely to some members of the Society for Technical Communication (STC) called “Climbing the Levels of Collaboration: Or, How to Harness the Power of Crowds (or your Coworkers).” I enjoyed the questions the most. Surprisingly all the questions were asked using the chat area of the conferencing software, not audibly on the phone.

I think people learned a lot. It was interesting that we veered off much more into Agile development territory than I had intended. One writer was in an organization just starting Agile development, and wondered how to work with documentation that was in chapter-based books. My suggestion was to do a content audit of those chapter-based books to try to determine what topics make up those chapters. Then, try to match topics with the Agile stories that your team would work on in a sprint. I must have content audits on the brain while reading by Content Strategy for the Web by Kristina Halvorson.

Here is the slideshow on Slideshare. You can also download a four-page PDF of the slides.

Storytelling and the Art of Community

I just received my pre-ordered copy of the Art of Community and wow! I am learning so much already. Jono Bacon is the author, and his experiences with communities come from years with the open source Linux project and now Ubuntu.

I believe many types of communities can benefit from reading this book, from professional organizations to preschool boards. So far I’ve only read about bikeshedding, governance, and conflict resolution, both areas I need to know how to handle!

The book opens with a story of a teen-aged boy racing across England to go to a meeting with people he has only met on the Internet – and he’s late! I loved this story as a hook for the book.

It reminded me of my own first-time experience with “Internet friends” (as the friend’s wife in the story calls the group.) My perspective was as a girlfriend whose boyfriend had the “Internet friends.” 🙂  Here’s my story.

It was the mid-nineties and my boyfriend Paul was working at a university as a system administrator. In his spare time, he stumbled across a group with a single goal that captured his attention – the team, the Internet’s first general-purpose distributed computing project. Their goal was to win a contest to crack or decode an encryption key using many computers, each one doing a small amount of the calculation work.

From Cincinnati, Paul got more involved with their project, and chatted with the group on IRC quite a bit. As strange as it sounds, I got to know the group through their IRC handles – cow, dbaker, Nugget, Moonwick, and decibel, to name a few. One week they decided it would be great to get together for dinner in Indianapolis. My girlfriends from college who lived in Indianapolis didn’t quite know what I was talking about. “You’re coming to visit? And visiting us as well as some new friends of your new boyfriend? And he only knows them through the computer?”

Paul and I drove over from Cincinnati to Indianapolis, about a two-hour drive. I wasn’t sure what to expect. I trusted Paul knew these guys well enough to want to hang out. I was a tagalong but my curiosity, which I have in abundance, was piqued. Would the first meeting be awkward or natural? Would I have anything to talk to them about?

palmpilotsAs it turns out, we had a fun time at a fondue restaurant. We were stuffed full of food and good laughs. The guys happily played with their gadgets – Palm Pilots were the popular one of the time.

Oh, good times. That meeting was the first of many for our group. We traveled to Atlanta later to scope out different locations for a company and at the end of that quest, many of them moved to Austin to work at the United Devices startup company in 2000.

Content strategy – so much to learn

I just ordered Kristina Halvorson’s (@halvorson on Twitter) book, Content Strategy for the Web after viewing “10 things every business person needs to know about content strategy” presentation (by Melissa Rach). Powerful stuff!10 things every business person should know about content strategy

View more presentations from mrsruble.

Reminds me that I need to get cracking on a presentation to supplement my book. I’ll finish up this blog post for now. 🙂

I learned a lot just by clicking through this slide deck so I am anticipating a good education from the book as well.

Content strategists seem to have interesting conversations around the #contentstrategy Twitter hashtags. I learned that PBS has a Chief Content Officer and apparently so does NPR.

I enjoyed the post with notes about content strategy on I’d Rather Be Writing, Three Questions To Start Thinking Like a Content Strategist. The link list at the end is very valuable. Another fascinating set of links for learning is on this Friday content strategy: installment 3 post. It has this excellent warning right up front: Caution: reading the following may make you passionate about content strategy and knowledgeable about recent content news.

So, consider yourself warned. Starting to read this post and clicking through to all the links may lead you through a most fascinating journey to learn more about content strategy.