Documentation with Blogs, Wikis, and Communities


Published on

While your documentation might not directly converse with users, learn about how wikis, blogs, and other social media technologies can enhance your documentation to help customers talk to each other. Given at the STC Summit 2009.

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • IntroductionsAnne - Blogger at www.justwriteclick.comSr. technical writer at ASIVolunteer writer for FLOSS Manuals and One Laptop per ChildJanet – Blogger at Techie Tech WriterSr. technical writer at EnthoughtVolunteer writer for FLOSS Manuals and Open OfficeVocabulary and Examples <number>
  • Let’s talk about the vocabulary you can build up for social networking technologies. Some of this will be a review for some of you. <number>
  • TaggingThe collective set of tags is known as a folksonomy - a taxonomy created by everyday folks. Where taxonomies are strict and rigid, a folksonomy is flexible and allows for any term. Both are powerful. clouds are a visual method of displaying tags that are used most often. Tag clouds use a larger font size or bold to indicate which terms are used for more content. Or, alternatively, some tag clouds could show the most popular terms based on recency of that tag being used.<number>
  • ambassadors are paid in lego bricksBlog examples for end-user help and release notes: Examples are new Google Calendar features and SmugMug, where the entire blog is dedicated to Release Notes. I've also found the Jing online help is written and maintained in Movable Type, a blogging tool. Jing offers for sharing your screencast content.Sun Microsystems – two technical writers on the NetBeans Ruby project presented “Engaging diverse audiences with screencasts, wikis, and blogs” at last year’s Summit. Gail Chappell and Cindy Church<number>
  • Have you already implemented an online help system with dynamic updates, or are you still tied to software release schedule? As customers become more accustomed to the immediacy of blog updates, they may increasingly expect updated content more often. Stupid RSS tricksFind out the \"Buzz\" on blogosphere with RSS – aggregation of information is crucial for this goalGet updates to classified ads based on a search or a category (example: craigslist)Follow group conversations (example: Yahoo Groups, which offers RSS feeds for conversations)Package tracking (example: ebay resellers say this is a useful tool)Product newsletters (again, RSS as an email alternative, still requires customers to opt-in, but they can choose not to be notified via email)Calendars to get RSS notification for birthdays, anniversaries, etc.Higher education (notification for course information)Create specialized searches with RSS notification for competitive intelligence and other specialized informationSearch for job leads on with RSS notification – has this feed running in the sidebar<number>
  • Communities gather around a concept or common goal not around a collection of content (although content does plays a major role, it is not the impetus for the community).Conduct audience analysisPilot first – read Wiki Patterns book by Stewart MaderBuild a wiki style guideOffer wiki how to guidesSet rules for arbitrationIntegrate the wiki with other contentEnsure that your wiki has original contentBeware of spammers, and back up often Keep updating content Offer training sessionsBecome a member of the communityRecruit other internal reviewers Category and template maintenanceWatch recent changesExpect small percentages of contributors and value them highly<number>
  • Twitter status updates can also update your Facebook statusHash tags build Twemes – Twitter themes at Now that is fully featured, hash tags are searchable.You could use an RSS feed subscription to publish microcontent on another online help system – tips and tricks.<number>
  • Profile – useful for user analysis and task analysis and persona work – naming personas Lets you find out more about your usersDo a search for iMIS on LinkedIn to find out more about my product’s typical end-users, also helped with persona names by typing in typical job titles and finding people’s names<number>
  • These two books talk about forms of payment in online communities – in whuffie. Whuffie is ephemeral, reputation-based currency.Technical writers may already be moderators in online communities. Starting out by communicating on forums or boards is an excellent way to establish yourself as part of the user community. Asynchronous conversation or synchronous - In the Agile Tech Writer, Sarah Maddox talks about answering Instant Messages from all around the world and being available to others to assist or just share humorous stories.<number>
  • Mashup definition - web application that combines data and/or functionality from more than one source.Map mashups are the classic example – here I’m finding a Wii within 25 miles of my zip code. There are 25 on craigslist alone. Wiinearby.netFor a user assistance example, consider that Microsoft has done for years is the combination of a hyperlink that actually opens a dialog box where the task will be completed. Remix within FLOSS Manuals lets content from several books be reused.<number>
  • This IS documentation on flickr for the iPhone. example of a system installation including priming inkI suppose “going viral” can be as dangerous as it is useful for instruction. <number>
  • Hold training sessions or meetings in Second Life – DITA users group that meets in Second Life. Using wii remotes (haptic controllers) for orkin training where physical objects need to be manipulated in a certain manner life – stability and scaling and griefersAnyone have questions on vocabulary so far? What have I left out? Hand off to Janet to talk about using a wiki system for Book Sprints – real world interactions.<number>
  • What about compressing all this conversation and community into an event for producing a document? BookSprint case studyBookSprint story – Adam Hyde of Floss Manuals had run one for Inkscape in ParisWe wanted one for OLPC – and I wanted it in Austin so that I didn’t have to travelBookSprint planning – who, scope, where-So we looked for funding-And we figured out who to invite-And that also shaped where we had it-Scope set ahead of the upcoming G1G1 release using mailing lists and emailBookSprint itselfFive days – half day of planning, three days of writing, half day of fun, then a day of cleanup getting ready to publish.Additional sprints – Circumvention, Firefox, Digital Foundations and CiviCRM<number>
  • Digital Foundations on Vimeo: slide is done, hand preso back to Anne<number>
  • If you are one of the early adopters for all social tools, you probably have started with LinkedIn, went to Facebook once it opened up beyond the college crowd, and then you were stymied by all the Naymz or Spock invitations that spread like wild fire. How can you evaluate all these newcomers and determine which ones have any return on the time spent with them?Some ideas for evaluating newly available tools: Determine which types of people in your network are using those, and specifically ask them what gains or returns they are seeing from that specific tool. Figure out your goals with social networking, which will help you figure out if you need to be on every single network, or if a specific few that are directly corollary to your goals are the ones to focus on.Trust just a few people's opinions on a tool - if she gives it a thumbs up, then try it for yourself. This technique may work well if a relatively obscure product becomes suddenly popular, but you do have the time to determine the usefulness for yourself, your company, and your documentation.Realize that not all social networking tools may be evaluated with an enterprise or corporate application in mind. In some cases, a try it and see grassroots effort can reveal much more about the tool than a few people evaluating with a checklist.<number>
  • There are two models you could follow – one is using the technical writer as personality and deliverer of content, sort of a sage on stage model, but another model involves the technical writer as a bystander but enabler of the conversation. In the second model, the tech writer is not the personality, but more like a stage hand who needs to understand the inner workings of the community theater to put on a good show. We can enable conversation through our user assistance without having to be the talking head or newscaster media personality.<number>
  • In their Social Media Marketing Playbook ebook, Darren Barefoot and Julie Szabo advocate that technical writers are excellent blog monitors and can easily handle multiple notifications from reading multiple news feeds or RSS subscriptions. If the technical writer is also maintaining a blog and online presence, commenting on others blogs in the field is a great way to join the conversation. Tools: RSS feeds, Google Alerts,,, Yahoo PipesSpend a day with technical support listening to their calls.If your product is sold on a website like, you can find conversations going on in the reviews and review comments as well as blog entries. <number>
  • Beth Kanter: – 5 hours a weekParticipate – 5 hours a weekGenerate buzz – 10 hours a weekShare content (blogs, YouTube, Flickr) – 15 hours a weekCommunity building and social networking (Ning, Facebook, LinkedIn) – 25 hours a weekShe offers that you have to stick with it for 3-6 months to see results. There’s a phased in approach to all of this - the final would be a community documentation project. <number>
  • Use your typical measures – reduced support calls? Less work for pre-sales folks?SXSWi three areas or channels for measurable conversations - Public Relations, Marketing (Sales), and Customer SupportDetermine your communication goals alignment – is it support? Sales or marketing? Public relations are another area that I don’t think tech writers need to sell themselves as.1. Traffic (but don’t trust it alone)2. RSS feed subscriptions – subscribers measure return visits and may indicate loyalty to the blog.3. Inbound hotlinks – how often do other bloggers or other websites link to this blog?4. Search position, part one - keywords for company brand and keywords5. Search position, part two - keywords for an individual’s brand (fame level)6. Voice – does the person blogging represent the promise of an online experience that you can “hear” and appreciate?I would also add:Number and frequency of comments, plus the variety of commenter’s voices can show the type of audience the blogger has gained.<number>
  • <number>
  • Documentation with Blogs, Wikis, and Communities

    1. 1. Anne Gentle and Janet Swisher STC Summit, May 2009
    2. 2. In my eighties, my best friends are in their fifties, and I have many friends at university. It keeps one young, and up with the vocabulary. That’s terribly important, especially for a writer. . Mary Wesley
    3. 3. folksonomy, taxonomy, tag clouds, social bookmarking
    4. 4. Blogs, community content, user-based content, user-generated, publishing, participatory media, screencasts
    5. 5. podcast, blog, weblog, vlog, video log, RSS, subscription, feeds, aggregation, news
    6. 6. wiki, user-based content, crowdsourcing, comments, discussion
    7. 7. Twitter, Pownce, BrightKite, poke, superpoke, status
    8. 8. LinkedIn, Naymz, Spock, Friendster, MySpace, Facebook
    9. 9. Forums, email lists, instant messaging
    10. 10. Map overlay, multimedia, launch from user assistance, machinima
    11. 11. Photo sharing, video sharing, viral video
    12. 12. virtual reality, Second Life, haptics
    13. 13. Zero to book in five days Video link
    14. 14. Nov08: Mar09: Apr09: July08: Internet Firefox, PureData, Inkscape, Censorship, DocTrain West, NYC & Paris upstate NY Palm Springs CA Berlin Aug08: Feb09: Mar09: May09: OLPC, Digital Command Line, CiviCRM, Austin TX Foundations FSF Annual Mtg, Truckee , NYC (Boston) CA This slide is not in the handout
    15. 15. Evaluating newcomers: LinkedIn, Facebook, Naymz, Spock? Twitter, Plurk, BrightKite?
    16. 16. Rockstar coders… legend or myth?
    17. 17. Photo courtesy Tools: RSS feeds, Google Alerts,,, Yahoo Pipes (Drinking from the social media firehose)
    18. 18. Listen, Participate, Share content, Build community, Network
    19. 19. Determine your communication goals alignment – Customer support? Sales or marketing?
    20. 20. Image courtesy Luca Cremonini, Source: Wikipedia, CC Share and Share Alike 2.5 Any questions?