I’ve published a long-ish article on the WritersUA site where I describe techniques for user assistance that let the user participate. It starts with simple techniques such as comments and moves towards community documentation efforts. Please read and share Putting the User in User Assistance. I’d love to hear what you think about these techniques.

While doing some research for LugIron, a startup here in Austin where I serve in an advisory role, I found a slideshow discussing signs of successful community launches by Joe Cothrel, a VP of service at Lithium.

Now, what they mean by “community” is a larger than 5,000 person audience, enterprise-type (B2B or B2C focused communities), and containing primarily forums and blogs (followed by everything else.) So, it’s not quite the same as the wiki communities that I’ve studied and participated in. But, what’s interesting to me is that one of his Warning signs on page 8 is a quote from the enterprise:

“We want to do a pilot.”

Huh? Really? Wanting to do a pilot is a warning sign of eminent failure? I guess with blogs and forums, you would want full dedication to the efforts and the goals of the community. But with wiki communities, I think a pilot is a great idea. Pilot content, pilot collaborators, pilot wiki.

What do you think? Do wikis fold up easier than forums? Are pilots getting a bad name in corporate-sponsored communities? Is this a case of the vendor wanting full dedication in their sales engagements?

I appreciated SocialText’s Ross Mayfield describing the various levels of interaction in his One on One interview with Fierce Content Management. The interview reminds me that social context alters behavior and motivations. Think of an intranet situation, where interactions are between bosses, colleagues, direct reports, and coworkers. The goals in this context are to increase productivity and collaboration speed, but corporate culture changes motivations. Then consider the context of an internet site, where interactions and customer relationships can be deepened and enhanced while providing customer service. Contributors to a wiki or any online content management system will certainly vary their behavior in accordance with the offline expectations of them.

I think it was in the book Groundswell that I read a case study where a company brought in a wiki, thinking that Generation Y employees would embrace it. But Generation Y wisely stayed away, because they didn’t have the authority required to make the system work well. Since the higher-ups stayed away from the new system, there was no leading by example, nor was there incentive for the newest, less tenured employees to use the system.

Patrick Davison is a digital artist living in NYC, and he designed the cover for my book. His Ignite talk has a similar theme – considering how your reasons for using a particular site or application (such as Second Life) shapes how you act there. The title is “The Plight of the Digital Chickens” and I think you’ll enjoy it as much as I do.

What are other examples of context shaping online behavior? I’m sure danah boyd has great examples in her papers.

Jakob Nielson and his research group, Nielsen Norman Group, have done it again – letting us know how users are actively perceiving and using social software for different business tasks. This research is important as the social web evolves so that we, as web content creators, know the best ways to present and offer different types of information, especially for corporate sites. He pulls it all together in an Alertbox from October 12, 2009 titled Streams, Walls, and Feeds: Distributing Content Through Social Networks and RSS.

What does this research mean for user assistance delivered through social means?

Voice matters – People wanted a specific voice for certain corporate brands. For example, the BBC was thought that it should have a more professional voice in its messages. But for other corporate brands, people wanted a more casual style, but the biggest reason for unfollowing a company rep on a social networking site was annoyance at the frequency of posting. My thinking? Don’t post your entire release notes links via Twitter in a week – instead spread them out to avoid drowning out the other people that your readers are also interacting with. I talk about finding your voice in chapter 7 of my book, and this research finding is certainly relevant.

Consider context – Updates that came through RSS rather than social networks such as Facebook, LinkedIn, and Twitter, were thought to be more “official” and trustworthy. However, readers have a lot more control over what they see – and readers who read the second page of a stream are nearly unheard of. They don’t seek out past postings. I have seen this happen on my blog here at JustWriteClick – once a post drops off that first page of about 10 posts, it’s only seen again when someone from a search engine looks for something very specific, such as the End-user Documentation in an Agile Environment post. What else is interesting about offering RSS feeds for information is that users’ habits haven’t changed in 3 years, though RSS use is on the rise and people are selective of the feeds they track.

Keep up – Twitter and Facebook are sites that are visited daily – can you keep up if you decide to engage customers there? And is there a place for end-user documentation on these sites? My take is that you shouldn’t start unless you’re willing to keep up. And in many cases, you probably don’t need to start on certain social network sites. If your group haa corporate goals like maintaining customer support by tying the social network interaction very tightly with your end-user documentation, then Twitter or LinkedIn may be a good match. Facebook may be a match also, depending on your message. Non profits, for example, find Facebook a great match for education, training, or raising awareness. If your corporate alignment as a technical writer is with the training and education department, you may find a niche case for using Facebook for promoting learning opportunites.

Make it useful - The most successful messages had substance, were timely, and met users expectations. Message usefulness scored the lowest of all the categories. Yikes. I would hope that as more content strategists and technical communicators apply their skillset to these messages, we can increase the utility.

Write well – Writing specifically for the medium is important to get the results you want. Probably the best way to write well for the medium is to read as much content as you can in the targeted medium. Apparently you can’t just repurpose content or use shortened text snippets that point to a longer one – users won’t click through.

Mobile findings

Only 4% of the users involved in the study sought out corporate messages from a mobile device. What I might infer from that finding is that mobile devices are for necessary in-field information, not for corporate messages syndicated through RSS or posted to social networks.

Email still fits

I found it interesting that email messages and newsletters may still be the best way to maintain customer relationships. Even though the user is responsible for deleting those messages, requiring more “work” than social networking sites, users still don’t browse through multiple messages from corporate “streams.”

Nielson’s summary says it so very succinctly that I can’t help but quote it directly:

Summary:
Users like the simplicity of messages that pass into oblivion over time, but were frequently frustrated by unscannable writing, overly frequent postings, and their inability to locate companies on social networks.

I loved the line, as delivered by Tom Hanks in A League of Their Own, “There’s no crying in baseball!” I know there are times when the crying must happen without delay. I don’t believe most workplaces actively encourage crying – at least not outside of acting careers.

When I’ve read Agile practitioner reports that tell tales of times when technical writers have left meetings and fled to cry, I am not just surprised but a little dismayed.In A Tale of Two Writing Teams from an Agile conference three years ago, one anonymous writing team reported one writer in particular crying during the daily standup and in retrospectives.

As the prioritization changed from the new Java web program (the new and fun stuff) to updating the old, stuffy legacy client server code, writers’ tasks switched from creating new online Help to updating old versions of end-user documentation (books). This change caused the writing team to revert to form—that is, they began to demand written design specs. It’s as if once the technology took a step back from online Help to written documentation because of the prioritization of the product backlog, so did the methodology choice. I tried my best to coach the writers to work creatively with developers on the old stuff as they had on the new, but there was an insistence that the existing specs
for the old legacy code would now become outdated, and the writers were completely uncomfortable with that. One writer—the one with the most tenure—
moved out of the team room, citing lack of privacy and her ability to contribute as the reasons (when I know that it was really a lack of embracing the change). I can remember several episodes of her crying during daily scrum meetings and in
retrospectives.

The paper author’s analysis indicates that the stress of embracing change caused the outburst I think the stress of change can bring on an emotional outburst, and sometimes people have crying as their stress release.

But what is more interesting to me as a content provider is that the change in the tools used to deliver the documentation seemed to correlate to the writer’s work habits. As I search for wiki solutions for collaborative authoring on Agile teams, I’m reminded of this article again and again. There’s no crying in Agile, and having an Agile documentation tool should help with change management. Except, of course, the change management associated with bringing in a wiki. Stewart Mader had great suggestions at the recent WebWorks Roundup: make wiki upkeep part of everyone’s job, make it as easy as email, and make it as sociable and enjoyable as riding the train to work each day. Any other ideas? I’d love to hear them.

I attended two days of the WebWorks Roundup here in Austin this week and served on a few panels. I enjoyed signing books as every attendee got copies of books from XML Press. It had featured speakers like Tom Johnson and Stewart Mader as well as sessions with Lisa Dyer and Alan Porter to name a few. Here are my summary take aways from the sessions.

Wiki adoption

Stewart Mader is a wiki consultant, probably the most experienced, practical, and sensible wiki adoption expert available today. His message about wiki adoption resonated with me as I look for collaborative authoring solutions for our Agile teams. He said, if you look around the enterprise, people have high adoption of email for their daily business tasks. In the adoption phase for a wiki or collaboration system, you can tie a wiki to email conceptually as this ubiquitous useful way to get work done. If you think about it, more complex systems have a higher learning curve, so people default back to email to get into their comfort zone. But, sending email messages is an isolating experience – email doesn’t let you work together collectively like a wiki does.

For example, working in the shared space of a wiki is like using light rail to get to work. He has made friends on the train he took each day years ago and he’s still friends with them today. In other words, being in an environment that enables social interaction is more powerful. He says to think about the business process a wiki affects – do not just apply what the Internet says to do with a wiki. The biggest and most powerful collaboration going on with wikis in the enterprise is group collaboration – small groups. You don’t want one-off contributions once, you want repeated collaboration and repeated use, as frequent as email and as a simple core tool that they use for everyday business. Preach it, brother!

He also talked about measurements to indicate that adoption is successful. One of the biggest dangers he sees is counting the number of pages created when adopting a wiki. Don’t do it! Better metrics are measure per time period or per some other unit:

Views                    Day

Revisions      per       Page

Comments                 Unit

Tags                     Type

Automation – 1001 Nightly Builds

Some of WebWorks’ customers gave talks and a panel discussion about automating software builds using WebWorks Automap. These were great eye-openers and my ears perked up because they were writers working in Agile environments. They have to release in tandem with internal development cycles, so they automated as much as they could. One doc group used to have a 15 page document on how to create a PDF complete with screenshots for all the settings. Mary Anthony from Palantir said their writers have to document 4 user interfaces, 3 admin GUIs, more than 12 servers and an API, and they used advanced techniques such as text insets in FrameMaker. Using WebWorks, another writing group had automated PDF generation, wiki output, plus HTML output, all from Framemaker source files.

This was interesting to me – they found there was a true documentation domain and it was hard for someone who usually builds software for them to put together docs. Terms like cross references, text inserts, and so on, were foreign to their build engineers. They don’t even have the concept of “book” as a collection of chapters with a TOC in Framemaker. Even using a Windows server to automate builds was outside of the build engineer’s knowledge.

I learned about a tool called Apache Ivy, which is an agile dependency manager. Using this manager helped them integrate their documentation builds with the product builds. Mary Anthony explained that Ivy waits for the outcome of another build – like a refrigerator holding chocolate pudding, Ivy opens the fridge door and gives the build process what it wants (the chocolate pudding, or the fine documentation).

Overall a great couple of presentations about automation from which I learned a lot.

Blogging and Web 2.0

Tom Johnson is a blogger and technical writer and likely the most subscribed-to blogger in our particular tech comm niche. He gave a great talk based on his blog series, Seven Deadly Sins of Blogging. In case you’re curious, the sins are being Fake, Irrelevant, Boring, Unreadable, Irresponsible, Unfindable, Inattentive. (I’ll link to the rest once he has the blog posts finished.)

He had great pictures representing each sin. My favorite quotes were from Penelope Trunk (The Brazen Careerist, Blogs without topics are a waste of time) and Stephen Fry’s blog entry, “Don’t Quote Me“.

This session was a great starting point for our next panel about Web 2.0, although we mostly talked about blogging. The Technorati State of the Blogsphere 2009 report came out yesterday, so it was useful to talk about some of the findings from it (73% of bloggers use Twitter as compared to 14% of the general population, for one.) I enjoyed talking with Alan Porter and Tom on this panel and I may have asked as many questions as I answered. All in all, a great two days of discussion and presentations.

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!

I’m so pleased to tell you that my book is available now from Amazon.com and BarnesandNobles.com and for sale in Austin, Texas at BookWoman on North Lamar. Published by XML Press, this book was fun to write, difficult to finish, and a dream come true for me, a kid who read 500 books in a school year in the second grade. I love books and I love this book especially. But I do want to keep improving it with blog entries here and responses to honest and thorough reviews, even negative ones.

This sample chapter is available (by direct PDF download or on Scribd) to start the conversation and I invite you to comment here or on Scribd.
Free Chapter Conversation and Community

If you’re here in Austin, I’m working on scheduling some book signings at local bookstores, and be on the lookout for an invitation to a book release party in the next few months! I want to share my excitement.

And lastly, I have to thank my blog readers – you are collectively loyal, smart, funny, and engaging. I couldn’t have written this book without you.

I gave a webinar this week for Scriptorium that will be available online titled “Documentation as Conversation.” The fact that it’s recorded lets you avoid scurrying around rearranging meetings in Outlook just to attend it. It sold out which was great to hear, but I like that the message and conversation continues through the recording. One of my fun examples was the Wordle visualization of my tags from the social bookmarking tool, del.icio.us.

During the question and answer session, someone mentioned they felt like social media made her feel like we’re becoming paleontologists. I think she referred to my many examples of how to “stalk” your users to learn more about them and their goals, especially if you document software. I search for my product’s name in Indeed.com job listings as well as look for job titles with my product’s name in LinkedIn to learn more about the people I’m writing for. I wrote up the technique in this blog post, Find your user’s vocabulary and use his or her key terms as keywords.

I also had a follow up email saying that people want to know, where should my team start conversations? Or where should we focus our time if we do start? In my book, I talk about phases: Listen, Participate, Share, Build a Platform. I think you should start with listening and monitoring what’s already being said. Next, start by commenting on blogs or by blogging yourself. A baby step towards blogging is to blog on an internal site, behind your firewall, just to limit your audience if that makes you more comfortable.

Also I’d recommend trying out tools that are already installed that you don’t have to maintain and install yourself. For example, I started justwriteclick.com on wordpress.com and paid $10 a year to map my domain name. When I knew WordPress was a good fit for me and my blogging and site needs, I went ahead and found an ISP and installed WordPress myself. And two years later, I’m hooked on WordPress and I’m even attending WordCamp Dallas in a few weeks.

Sharing content is the next step, and the final step is providing a platform for users to bring their own content in. These steps take time but you will learn valuable lessons along the way and hopefully avoid any stumbling or disastrous results. It’s okay to fail, though. You learn new lessons with each attempt and approach.

So keep an eye out for the recording of the webinar, Documentation as Conversation. The price remains at USD $20 and you get to schedule listening to it any any time of the day. It’s an hour long and if you do listen to the recording, feel free to contact me via email with any questions. I am looking forward to hearing even more feedback!

I’m writing this as the rain falls down in Austin, Texas. I’m learning that with practice, you can learn the ebb and flow of a conversation and become a meteorologist for the “social weather” that’s ongoing in a community. For an example of social weather, do what Clay Shirky describes in his description of the course with the same name at New York University. Simply make some observations next time you walk into a restaurant. Is it noisy or quiet? Slow or busy? Are there couples or groups dining? That collective atmosphere is the social weather, which I first read about on Jason Kottke’s blog.

In a restaurant you have visual and auditory cues to give your inner meteorologist a chance to assess the social weather. In an online community, you need to understand the cues that occur in writing, in emoticons, and in frequency and intensity of updates to content. In the presentation “Blogs and the social weather” at the Internet Research 3.0 conference in October 2002, Alex Halavais describes a deep dive into analysis of blogger’s discourse.

“By measuring changes in word frequency within a large set of popular blogs over a period of four weeks, and comparing these changes to those in the ‘traditional’ media represented on the web, we are able to come to a better understanding of the nature of the content found on these sites. This view is further refined by clustering those blogs that carry similar content. While those who blog may not be very representative of the public at large, charting discourse in this way presents an interesting new window on public opinion.”

While this concept may sound new and exciting, it is quite 20th century. I was surprised to learn that analyzing newspaper content to determine public opinion was researcher Alvan Tenney’s original concept in 1912. 1912!