Category Archives: social media

What’s New in Conversation and Community?

Conversation and Community 2nd Edition Cover

Love this new cover, both photos are Creative Commons licensed once again. Let’s look between the covers though!

While thinking about the second edition and how three years had passed, I was pleasantly surprised that we could get to the three year mark with the book’s content remaining relevant and accurate. Seems nearly impossible on such a fast-moving topic as the social web. Yet while looking through the tools chapter to update it, we mostly tested URLs and looked at the categories. Surprise, nearly all example tools are still relevant and useful to technical documentation. Not all the exact examples still existed, but that was just interesting to revisit.

Next, I examined the book for three areas of improvement – organization, content updates and additions based on my most recent experiments and experiences with OpenStack at Rackspace.

Reorganization

With the tools being so much more a part of every  day life and work now, I have moved the “Concepts and Tools of the Social Web” chapter to become an appendix. It also lets readers go right into “Defining a Writer’s Role with the Social Web” where I walk through a strategic approach to the social web. I also moved an entire section about managing community methods into a new chapter titled “Analyzing and Measuring Web Techniques” to expand on the management practices and business value tie-ins.

Additions

Some of the best additions to the book are interviews with practitioners I’ve met over the years who are doing community-based documentation already. It’s a balanced mix of open source communities and corporations using community to add value to their offerings. These are scattered throughout the book. I answered these same questions as well about how my current work is structured.

Based on my observations with documentation comments over the last year and a half, I added plenty of commentary and guidance to “Commenting and Connecting with Users.” Selecting and implementing a commenting system is chockful of requirements and guardrails for comments included on every page of your documentation. I also give an example of how to process comments daily, weekly, and moderate comments.

I added some additional information to the wikis chapter based on my recent experience with a Google Summer of Code documentation summit, comparing and contrasting “typical” wiki writing to planned writing. Many wikis have become web content management systems that encourage collaboration, so while I continue to address wikis in a separate chapter, the community and conversation building remains at the heart of my book. For wiki-specific tactics using Confluence, I’d highly recommend Sarah Maddox’s book, Confluence, Tech Comm, Chocolate, which I reviewed previously.

I added a chapter about content strategy for community documentation. I’m definitely sensing a strategic specialty opening up right now, and want to keep exploring it through the lens of content strategy. There’s a great case study included as well about Autodesk and their learning communities. An interview with Victor Solano with Scot Abel lets you “explore how the software giant has leveraged the power of the crowd, software standards, and content management to meet the fast-changing needs of its customers.” I found it thought-provoking and inspiring.

If anyone would like a signed first edition, please let me know by sending an email to annegentle at justwriteclick dot com. We’ll work out shipping and payment (Paypal or check-in-the-mail) with the few remaining copies I have!

Choose Conversation and Community

We’re closing in on the second edition of my book being released and available! I’m super excited about it. I can’t stop thinking about it. On the way back from the O’Reilly Open Source Convention, I started doodling in a new notebook when all “items with an on/off switch” had to be off, and came up with this diagram for what the social web means to me.

The terms social relevance, social networking, and social media, as a triad for explaining the social web became very clear to me after reading this rather complex title: Enterprise Social Technology: Helping organizations harness the power of Social Media Social Networking Social Relevance by Scott Klososky.

Social Web

You see, these three social powers offer us content folks an entry to the strategic playing field of the social web.

What I realized is that there’s a stream of conversation and community throughout all these social threads. I hope that the second edition of my book connects these threads with more clarity than ever. I hope the long title doesn’t prevent you from tweeting about it. And I hope we all can relate our stories to each other to keep learning about the social web and growing our field’s influence on it. Let’s choose conversation and community as a strategic benefit to all our documentation efforts.

Facebook for Social Support? I like.

When we first rolled out TryStack, a place for trying out cloud! for OpenStack, we heard the groans from the audience since our first ID check is through a Facebook login. No Facebook, no TryStack. But since we’ve worked through the manual process and put a straight-through “Login using Facebook” link on the Dashboard, I have to say the process is super easy and repeatably so.

And I’m quite glad that we have the TryStack Facebook group for people to ask questions specific to TryStack. As the OpenStack doc coordinator I’ve found the group to be very valuable in telling me what information they’re missing, where they get confused about usage, and so on.

I especially like the video linking I can do in Facebook comments. Here’s a link to a video I made introducing people to TryStack.

Best Twitter Account Idea Yet from The Information

You know how all these bizarre yet entertaining Twitter accounts keep popping up? The character-based Mad Men account, @BettyDraper the one quoting his hilarious father (with the not-censored four-letter-word-in-the-title), the FakeSteveJobs account, and how about this insane spam one, @horse_ebooks, told in the Ballad of @Horse_ebooks? Best quote in that article, “The reason it hasn’t been shut down yet is the same reason it’s so hilariously terrible at its job: It doesn’t bother anyone who doesn’t want to be bothered.” I’m sure I don’t have to tell at least half of my readers about the Fake AP style book Twitter parody account. It’s sheer awesomeness.

I have a new fake Twitter account idea. It’s inspired from The Information: A History, A Theory, A Flood
by James Gleick, describing the era of the telegraph, where you were charged by the character. Yet people still wanted a sense of efficiency and value from their telegraph messages.

How about this entertaining Twitter account idea – a Twitter account entirely written in a code that you need an old telegraph code book in order to understand?

Apparently people in the 1880s wanted to be sure the receiver of the message understands manners and respect. One of the subtitles of “Bloomer’s Commercial Cryptograph” states “By the use of this work, business communications of whatever nature may be telegraphed with secrecy and economy.”

Bloomer's Commercial Cryptograph

This book, Arnold’s Telegraph Codes, ensures the use of “Yes sir” and “No sir” throughout.

Arnold's Telegraph Codes

It would be a fun cipher each day or week, to figure out the contents of the message. Pretty sure it wouldn’t be guaranteed to be secret nor economic, but I bet we could ensure the use of Yes, sir, and No, sir.

Yes, these are the sorts of ideas I have about Twitter after using it for five years. What’s fun to me? Ciphers, information, history, and Twitter.

Exciting Future for Collaborative Printed Electronic Books

The future of the book is in your hands from Sourcefabric on Vimeo.

Sourcefabric builds open source software to support independent media worldwide. On February 14th, we’ll announce our tool to help people and organisations write and publish great multi-platform books.

Write and publish great books ready for iPad, Kindle, Nook or print within minutes. Write, translate or reuse content by yourself or with others and let the platform take care of structure, formatting, licensing, versions and export to book formatted pdf, epub, odt or html.

Share, reuse and remix content, chapters or even entire books. For example, import an epub from Gutenberg or a colleague’s textbook, rework and then publish to archive.org, lulu.com or another bookmaking community!

February 14th 2012. The next chapter in publishing.

http://www.sourcefabric.org

Google Summer of Code Doc Summit Stories

On my way to the airport after an intense and enjoyable three day session with four open source projects writing a book apiece, I wonder if I have any more words to write down. The group I worked with had 14,000 words in the system by day two. I feel I need to try to capture this experience. I’m feeling a little badly about coming home early – they are still working hard at it today!

The four projects were KDE, OpenStreetMap, OpenMRS, and Sahana. Each project brought 3-5 participants. Some of the participants didn’t know they had applied to write a book in three days. One project already had a long outline, reviewed by other community members. The participants’ backgrounds varied widely – tall, wide Python developers with long hair in a ponytail, disaster managers with cropped hair and glasses, a geology professional with a travel bug, cycling data wranglers and web developers, C++ developers and young gamers, a user advocate who also happened to be a grandma, and then there were the doc aficionados who find all of this quite fun, like me.

We all started the week with an unconference led by Alan Gunner from Aspirations technology, who has a way with words and a distinct gift for engagement. No one hid behind their laptops (though sneaking a peak at a small screen like a mobile phone did happen sometimes). About thirty of us were gathered, and I feel I’m leaving with a sense we have built a community of practice, that I can contact any other attendee to talk docs. What a valuable gift from Google, whose Open Source group funded the week with lodging and food provided.

Story telling

People were quite transfixed by the idea that a book can tell stories. Part of uncovering a story to tell involves audience discovery. FLOSS Manuals community members like Janet Swisher led the teams through an audience analysis exercise. These were her questions:

  • Who is using your tool?
  • Why do they use your tool?
  • What kinds of things are they trying to do?
  • What can you assume they know?
  • What do they probably not know when they approach your tool?

For these exercises, free agents like myself were assigned to one of the four teams. I went to the Open MRS team, which provides medical record software for developing countries. This was a great chance to learn how open source affects human lives. I learned how important it is to know who is setting up their software and why. Turns out, the majority of the project’s communication is with people who want to build a module for OpenMRS in their specialty domain. There are also implementers who want to use OpenMRS as a data store, turning their paper input forms into a form the registration desk can use when a patient reaches the front of the line at the clinic. They’ve also recently seen an uptick in requests to integrate with the OpenMRS platform, such as inquiries from Doctors Without Borders.

Parts of answering the “who” question also led to answering the “why” question – they use the tool because they need some extension of clinical functionality, they need a customization for a particular strain of drug-resistant tuberculosis, or possibly just because “their boss told them to” which then leads to investigation of why their boss wants to use OpenMRS. Mobile data entry and data retrieval as well as language support were parts of the reasons why they’d choose OpenMRS. Some of the stories that came out were not yet well-articulated, but discussing real people with real work was a huge help. I envisioned implementers taking an input form and making an online form, studying the data model while they did so. I heard about patients not making appointments but waiting in line for hours at a registration desk where they would be received for an observation by a medical professional, I wondered about the person accepting shipment of boxes of medicine. These every day tasks capture your attention and hopefully can be translated into a better, more engaging read.

Wiki writing vs. Book writing

On the morning of our third day together, one of the participants made a fascinating observation about the process of writing a book – that he actually approached the act of writing differently this week, with more focus on completion and quality, since he wasn’t writing in a wiki. In a wiki, he expected to be able to write in an outline, freeform, and someone would come behind him, he assumed, and make the text better. But knowing that the final deliverable was looming at the end of the week, he wrote more carefully with an audience in mind when he wrote in the FLOSS Manuals booki tool. This single observation captured my attention. How many others feel this same way when they contribute to your project’s wiki? I tend to avoid that problem by strictly stating what information goes into the wiki, in hopes of also focusing better writing attention in other areas, I guess. But what about writing for a linear, printed book, versus writing for a website where every page could be the first page? I believe us practiced pros know we can improve upon the classic act of writing by writing for personas and telling stories both for a book deliverable or an engaging user experience on a website. But it is certainly a tough task to coach others to do so. I felt that the book sprint experience, compressed and yet with elongated days of intense collaboration, was a great method for coaching improved writing in others.

Result: Books

Three of the four books are now available on Lulu. The covers look fantastic! Congrats to all the authors and many thanks to Adam Hyde of FLOSS Manuals, the Google Open Source Programs office, and everyone who took the time to make these books shine.

OpenStreetMap Sahana Eden

KDE Guide

 

Social Support and Documentation Communities

Stories of Social Media Sticking in Unlikely Places
Saying, “No one reads the manual” just doesn’t hold water any more. Social technology has intersected even the classic user manual. There’s always someone who will read a book. But their true motivation may be a desire to become an expert on a forum or on Twitter, building an expert’s reputation or reciprocating assistance because they know they can rely on the social web to pay it forward.

The way to amplify knowledge is through social media, social networking, and social relevance tools, gathering a wider audience and working in an economy whose payment is in links and more links. To find a fix for a problem with a cell phone, some chose to go to the phone’s web site and download a manual. Others naturally search on YouTube for troubleshooting hints.

Social media for troubleshooting, training, or trying software or gadgets? Sure. Does this scenario sound familiar?

“The darn thing won’t sync up again,” she grumbled as she tried to unload the latest running data from a sensor in her shoe. The data should travel from the shoe to the iTunes software through her iPod which was connected to her computer so that the data would be uploaded to a third-party website. As you might guess, her first troubleshooting attempt started with the error message within iTunes itself, but after seeing a message from iTunes that told her to reboot the router, she instead opened up a browser window. Without even opening a new window, she searched on Google in a browser plugin. A helpful community posting from a year ago helped her get the data about her five mile run from her shoe to the website.

Google is a new entry point to every help system that is, well, helpful. From Google users can view videos, download PDF files of the manual, and read forum posts from people who have come across this problem before. Sometimes Google links go directly to a company’s set of manuals, but more often than not, Google is the entry point to user-generated or community-collected content from blogs, forums, or wikis.

Bloggers who build a reputation as an expert in Adobe products can now be found even more easily with the Community Help search tool, which is a curated collection of blogs, video tutorial sites, and other social media-centered sites. Searching within the Community Help on keywords such as “footnotes” offers up a list of links to Indesign experts who maintain blogs and offer how-to tips and advice.

If people are listening on Twitter to come to other user’s aid, even microblogging and instant messaging applies to the new aggregate troubleshooting guide. Social support communities crop up when social media tools are used to collect questions and answer them or point people on the social network to others who can answer their questions.

Documentation communities are built upon content systems such as wikis that lower the barrier to contribution by giving any page an Edit button. Rather than waiting for a long publishing process to finish, readers can be come authors and editors at the click of a button. And the publishing system itself notifies users when new content is brought on board.

Social and community techniques are a sensation everywhere, even for the boring, unsexy systems applied to customer support and technical documentation. You’ll be glad for it the next time your favorite portable gadget does an unfamiliar flip flop.

Twitter’s Value to Technical Communication

Some responses to an inquiry I got via email from a student at the University of Minnesota in the Scientific and Technical Communication program. Thanks Mary, for asking nice thought-provoking questions!

1. What do you think is the value of Twitter compared to other forms of communication?

To me, the value of Twitter is that it was built based on the patterns some people saw of the ways people were really communicating online – In this interview with Noah Glass, one of Twitter’s founders, a journalist learns that Noah was reading myspace postings and figuring out that asynchronous, status-like updates were how people were really talking to each other online. The value of Twitter that I see after reading that article is that Twitter modeled itself after reality. It works well with mobile devices, a communication device that needed to fill a void in 2006-7. It’s hard to compare it to email or texting or instant messaging, when it’s a messaging system we didn’t know we needed until we had it. Recognizing and filling that need is how Twitter is thriving today.

2. Can Twitter really be used for documentation and if so, what are its unique qualities?

Sure, people are using Twitter for posting tips and tricks and encouraging others to do the same. It’s also being used for Twitter chats, periods of time set aside to talk on Twitter with a particular hashtag collecting and aggregating all the tweets within the time period. Tweets with a certain hashtag can also be displayed alongside online content that serves as documentation. Twitter can be used for the goals met with traditional documentation when the goals are customer support or service, engagement, adoption, research and feedback loops, and other similar customer-serving goals that doc fulfills. So yes, Twitter can be used for documentation, when documentation’s goals align with some Twitter use cases.

3. Are there any accessibility problems facing Twitter and what are the best ways to make Twitter more accessible?

Accessibility improvements usually apply to vision impairment, and the popularity of the iPhone or other smart phones that automatically eliminate most vision-impaired users mean that Twitter is not easily accessible to those usually served by accommodations such as screen readers. I don’t have real suggestions to make Twitter web content more accessible – I actually believe the mobile devices need to become more accessible to vision-impaired people. Touchscreens just aren’t going to cut it.

What’s more interesting to me are the articles about how much social media like Twitter suffers from a “club” problem – it can amplify how disconnected we are with other cultures. For example, when some BET award show topics started trending and some people on Twitter commented as if to say “I didn’t realize ‘they’ were here” I was mortified as were others. That lack of vision and close-mindedness is a huge social problem that social media can amplify. Also, there’s an often hidden advantage that doesn’t have to do with disabilities necessarily. Those of us with fairly “boring” lives (no horrid exes, no fear of violence or retaliation, no fear of identity theft or libelous charges) can use Twitter or other social platforms without fear, but others who grew up in gangs, had to reinvent themselves to avoid prosecution, or people who are chased by violent family members cannot use Twitter unless they’re willing to take much more risk than others.

Learn about Leveraging the Social Web for Customer Support

The webinar and interview we recorded last week thanks to MindTouch is now available for your listening and viewing pleasure. I had a blast talking to Scott. I thought we might argue a bit on some of the points, but we were in much vehement agreement that day! It’s just over an hour long.

video platformvideo managementvideo solutionsvideo player

After the webinar, I answered a few questions on Twitter that were interesting and we didn’t get time to discuss during the hour. I liked this one from @bmdesignhki, Asko Kauppi:

How about making LESS documentation, by having customers scrap out the unnecessary parts. Who likes documentation?

My response was:

Love the question about making LESS docs – I think web analytics will let us be ruthless in our deletions! :)

I am still ruminating on this a bit, though. How can we enable our customers to be ruthless about deleting the documentation on a site? We’ve carefully crafted this content, might even have a strong feeling about it, even (gasp) ownership! A customer won’t have this difficulty letting go of the words, so to speak. But if the analytics say it’s gotta go, it’s gotta go. Nearly all the web analytics work I’m doing right now is tightly access controlled. We can send reports to the community, but I don’t know if I’d want the community to do my deletions. Especially if one of the community members was prone to say “Who likes documentation?” Hee hee. Not sure about crowd-sourced deletions, but it does seem like it’s a great job for a fresh cleanup crew. Maybe instead of Earth Day clean ups, we need more Content Day clean ups. Definitely got me thinking more about clean lines and clean docs.

Another question that came through on Twitter was from @djtowne, DJ Town, she asked:

What metrics should social support sites provide?

My response was definitely truncated as 140 characters is hardly enough to respond within, but I said:

re: social support metrics: new v. return visits, time on site, what are they searching for? Comment response metrics for sure.

The longer answer is contained in this post, Web Analytics for Technical Documentation Sites. I have more ideas as well but I’m doing some research with my own OpenStack community documentation to test out some theories. Until I blog again, enjoy the webinar.

Trends and Open Source Writing

I get the greatest emails sometimes, thanks to my blog. Here’s the lead-in line that especially piqued my interest:

“I’m researching trends in technical communication for a grad-level writing class,”

She had me at trends in technical communication. And research. So of course, I read on.

” and I’ve found lots of posts on the web by established tech writers who specialize in the open source arena and who appear to be fairly entrenched in technical industries. Any references to the wanna-be writers in the same environment are followed by quips about their being poor, because they have to do a lot of jobs gratis to make a name for themselves.”

At the time I received this note, I had just started in my role as a technical writer and community doc coordinator for OpenStack, open source cloud computing software. I was surprised by the juxtaposition she noticed just in researching web posts, so I read on.

“Maybe I’m making the wrong inference, but it also seems that the comments about new writers are referring to grads who fit the traditional model of the 22 to 25-year-old coming right out of college. For my essay, I’d like to talk about the trends in Open Source where the “new” writer is middle-aged, possibly even retired, with years of expertise in a non-techie industry.”

Wow, I thought. A thesis about Open Source writers. I remember riding with Janet Swisher from Austin to Dallas for last year’s (2010) STC Summit, and we could count on both our hands the number of Open Source writers we know. This is a small group to study but a fascinating group in which to look for trends. Plus, I’m in a position to recruit writers who want to write for Open Source projects.

“Based on your experience, do you see an emerging need for writers (we’re talking paid gigs) who have lots of expertise in other areas, but are looking to switch to tech writing for their next career or as a part-time job in retirement? What avenues would be best to explore in the start-up phase?”

This thesis could help me understand this small group, so I responded and encouraged others to do so. But. I was left with trying to decide if I agree or disagree with her thesis, that Open Source attracts retired writers with years of expertise in a non-techie industry. I wanted to sift through which points I disagree with.

1. Age or years of experience in Open Source writers: The tech writers who are established in open source are often highly technical but not necessarily in a certain age group. I would say their technical skill set is the thing they have in common. I honestly haven’t met an early-20-something open source writer yet, come to think of it. I think you have a lot of work to do to “prove” yourself when coming to many open source projects as a volunteer. There’s a lot of meritocracy where only your work matters, not your methods necessarily. Here’s an example of what I’m talking about. Open source projects often use wikis (extremely lightweight CMSes) for documentation. Experienced, entrenched-in-the-enterprise writers are surprised at how effective a wiki can be for authoring and delivery, especially when they’re used to an Adobe toolkit. So, from where I sit, I don’t currently see “a trend in Open Source where the “new” writer is middle-aged, possibly even retired, with years of expertise in a non-techie industry.” Also, writers in open source nearly always come from technical industries.

2. Having to take lots of jobs gratis to build a reputation: Yes, you would have to do some jobs for free to make a name for yourself, but I’m doubtful that new tech writers have the experience needed to be a huge contributor or lone writer on an open source project. I say that because I have talked to college students (more than 10) about helping with FLOSS Manuals work or with OpenStack and I haven’t seen big contributions from any of them, yet. I’ve also invited college students to book sprints with little response. College graduates are another story, but I have no experience with recent grads to speak of, so I don’t have even anecdotal data to share.

3. Emerging needs for open source tech writers?: I definitely don’t see an emerging need for “new” writers looking to switch to tech writing or part-time in retirement to seek out an Open Source writing gig. That said, through FLOSS Manuals I have definitely met and worked with seasoned (but not retired) publishers and writers who have great contributions writing, testing, and publishing pages and pages of information. These weren’t paid gigs, although these volunteer opportunities certainly lead to great opportunities

These are just my observations in less than five years participating in open source communities. How have your observations differed?

Open Help Conference, Cincinnati, OH June 3-5, 2011If you’re interested in open source and documentation, please take a look at the upcoming Open Help Conference coming up June 3-5, 2011 in Cincinnati, Ohio. I’m the new kid on the block, embracing these techniques (maybe hugging them too hard?), looking forward to learning a lot and sharing my experiences. I hope you’ll join us!