Here are my notes from Darren Barefoot’s talk, a self-described recovering technical writer.
He leads with what defines social media? Create your own definition around these concepts:
Conversation - comments on large media sites allow ayone to speak to the media person keeping on the pedestal
Collaboration - 7 million people collaborating on wikipedia, likely the largest collaboration in human history
Sharing - some sort of microbroadcasting is built into every type of website
Scope - there are no longer 42-minute hours on televisions. Your buckets of stuff and time are sliced and diced. Ebooks can be 10 pages to 1000 pages.
Community - constructing affinity groups is easy, accessible
Transparency - blogging encourages transparency - medium is the message
Authenticity - example of knowing it’s fake is fakeSteveJobs.com, Lonelygirl15 is an example of outed fakery
42% of Chinese internet users have a blog
“The people formerly known as the audience”
Survey of 1200 bloggers - why do you create content, do social media? Talk to friends and family first, Keep personal history, Emote top three. But make money bottom response.
An excellent, engaging talk, with the conclusion being, there’s no way to relinquish control, it is already too late.
Here are the takeaways he left us with:
Relinquish control - realize that the best documentation for your product is already not on your website.
Users will help each other - put screenshots in Flickr to make it easy for your users to grab them and use them in their own doc
Empower your most passionate users - for example, the Red Room Chronicles created by a Marriot business traveller. He must be the most passionate hotel user known. Offer those users previews, invite them to focus groups, make them feel special.
Think outside the page - Twitter troubleshooting tips, and of course, remember video and photos.
Go where your users are - find their community spaces, be present as needed.
I had an “ah ha” moment at SXSW Interactive, when one of the social media metrics panelists Rohit Bhargava said he sees three areas or channels for measurable conversations - Public Relations, Marketing (Sales), and Customer Support.
For me, those three categories crystallized this connection: where our role as tech pubs is strongest in an organization, that’s where we might start successful conversations.
Gordon McLean’s post cites Marketing and Sales as a strong tie-in, and sure, I’ve seen that and worked in that type of environment. Marketing concepts such as Business Service Management and white papers about ITIL were the primary reason and communication idea I used when I started my blog at talk.bmc in 2005. Product documentation that helps drive sales or close deals is a great method for proving our value.
Tech support seems the best alignment for many companies, as Charles Jeter’s follow-up points out. Tech publications that drive down support costs are another area where value proof lies.
Where tech writers don’t stand much of a chance, based on my limited experience, is public relations. We tend to be a fact-finding lot, not the “spin doctor” type, nor are we necessarily prepared or educated in the ways of crisis communication. I myself cringe to think of having to write blog entries for Southwest Airlines after the recent safety fine. There’s a great case study on crisis communications at BlogWrite for CEOs - Case Study: Southwest Airlines’ Corporate Blog and Crisis Communications and reading it makes me realize how difficult it can be to blog for a company as a representative of a company.
Now, my question is, will companies pay technical writers for a conversation rather than a deliverable? Perhaps only if there are some metrics to prove worth and value.
Another one of my takeaways from last week’s South By South West Interactive conference is that it makes sense to use the term “social networking” rather than “social media” to describe sites and tools that help you stay connected with others. We’re not all journalists, and the “media” part of the term seems to signify that you want to share media, but in reality, you want to share interests, ideas, and connect with others.
Please feel free to add me as your friend, add a comment, join a group, connect with me on The Content Wrangler Community. I’d like to get to know my readers!
This book was an easy, fun, read, and seemed especially pertinent after all the immersion into social networking I’ve been doing with SXSW Interactive. The 100-page book, Getting to First Base: A Social Media Marketing Playbook, is aimed at your company’s marketing department for them to read before deep-diving into the social media landscape. Julie Szabo and Darren Barefoot share their stories and even their somewhat embarrassing lessons learned, sparing you from the same fate while also encouraging you to start the conversation.
At talk.bmc our entire intent was to start the conversation. So I know how daunting and intimidating it can be, yet you also have to dive in and sit back and listen. It’s not an easy road to walk. But sometimes ROI stands for Risk of Inaction, so eventually you should learn your way around the tools of the trade. I still like Reach Or Influence for the ROI acronym when applied to blogging.
This book gives you specific examples of tools and technology you can use to start the conversation, and also has the proper amount of caution about being genuine and having good intentions. One of my favorite quotes:
The vast majority of products are
ordinary. Worse, most customers
have made their buying decisions
about staple purchases years ago,
and it’s difficult to change their
minds.
So, what to do? Pull off the “online equivalent of a publicity stunt,” create a meme. To me, this is such a daunting task I can’t imagine writing a book about how to do it. But sure enough, these two have the experience and case studies to show for it.
I also liked the “influencer” chapter, describing the rules for interaction with bloggers. Looking at it as a blogger rather than a marketer, it’s good insider information to have. For example, check out this trick! Let’s say someone has a feedburner feed, but they haven’t published that little graphic that shows how many subscribers they have. Just insert /~fc/ into their feedburner URL, and voila, you have the little graphic! Example: http://feeds.feedburner.com/~fc/JustWriteClick. Super secret way to check out your friend’s blogs and see if they have any subscribers to speak of.
Glory be, they like their technical writers as monitors!
Darren has a background as a technical writer, and when the book talks about who is a good candidate for the sometimes time-consuming task of monitoring the blogosphere, I’ll bet it’s Darren who’s giving the nod to the technical writer. My other favorite quote:
On the development side, technical support engineers
or technical writers are often a good choice. They’re good
communicators, tend to have a broad awareness of the
company’s products, and can even reply to basic
support-related posts.
I agree whole heartedly. I think the Agile technical writer that Sarah Maddox describes is precisely the right person to be identifying keywords, get RSS watch lists configured, and read, read, read, and respond when necessary or find someone in our company who can respond correctly.
Wikipedia doesn’t like marketers - tread carefully
And, my personal favorite topic, wikis, is addressed. The book has an excellent section about what to do and what not to do when it comes to the tricky waters of Wikipedia. To me, this section alone is worth the $29 for this book! Solid advice with the proper amount of respect for the community behind Wikipedia.
All in all, nicely done and a great read for marketers and bloggers alike.
Lisa Dyer and Alan Porter presented at last week’s DITA Central Texas User Group meeting, and both told tales of end-user doc written and sourced in DITA, with wikitext in mind as an output. About 20 people attended and we all enjoyed the show. I wanted to post my notes to follow up, and I’ll post a link to slide shows as well.
This post covers Lisa Dyer’s presentation on a wiki sourced with DITA topics. I’ll write another post to cover Alan’s presentation.
Although, actually, first, Bob Beims shared Meet Charlie, a description of Enterprise 2.0. Seems very appropriate for the discussions we’ve had at recent Central Texas DITA User Group meetings talking about wikis and RSS subscriptions and web-based documentation.
Lisa has made her presentation available online. My notes are below the slideshow.
DITA source to wiki output case study
Lisa Dyer walked us through her DITA to wiki project. Their high level vision and business goals merged with a wiki as one solution, and Lombardi has customers who had requested a wiki. Lombardi’s wiki is available to customers that have a support login, so I won’t link to it, but she was able to demo the system they’ve had in place since July 2007.
What wiki toolset - open source or entprise wiki engine?
On the question of choosing an open source or enterprise wiki engine, Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help? They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you “vote” for updates and enhancements with dollars rather than, say, community influence. (Editorial note - I’m opining on whether you get updates to open source wiki engines through community influence. I’m certain you can pay for support and enhancements to open source efforts with dollars.)
Run a pilot wiki project
She recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. While Michele Guthrie from Cisco couldn’t present on the panel at the last minute, she also has found that internal-only wikis helped them understand the best practices for wiki documentation.
Meet customer needs - or decipher what they want and need
Lisa said that customers wanted immediate updates, knowledge of what’s new with the product and doc (800 pages worth), and wanted to tell others what they had learned. She found that all of these customer requests could be met with a wiki engine - RSS feeds, immediate updates, and the ability to share lessons learned. At her workplace, customers work extensively with the services people and document the implementation specifically, and that information could be scrubbed of customer-specific info. They found that rating and voting features give good content more exposure. Also, by putting the information into wikis, they found that there were fewer “I can’t find this information” complaints.
Intelligent wiki definition and separate audiences for each wiki
They have two wikis - one is for end-user documentation, one is for Services information. In the screens she showed us, Wiki was the tab label for the Services wiki, Documentation was the tab label for the doc wiki. The Documentation wiki does not allow anyone but the technical writers to edit content, but people can comment on the content and attach their own documents or images. The Services wiki allows for edits, comments, and attachments. The customers and services people wanted a way to share their unsanctioned knowledge such as samples, tips, and tricks, and the wiki lets them do that. The Services wiki has all the necessary disclaimers of a community-based wiki, such as “use this info at your own risk” type of disclaimers. Edited to add: The search feature lets users search both wikis, though.
Getting DITA to talk wiki
There are definite rules they’ve had to follow to get DITA to “talk wiki” and to ensure that Confluence knows what the intent is for the DITA content. For one, when they want to use different commands for UNIX and Windows steps in an installation or configuration task, they would use ditaval metadata around in the command line text (using the “platform” property) and use conditional processing for that topic. However, because of the Confluence engine’s limitation of one unique name for each wiki article, they had to create separate Spaces for each condition of the deliverable (UNIX Admin guide or Windows Admin guide, for example). This limit results in something like 12 Spaces, but considering it’s output for several books for separate platforms, 32 individual books in all, that number of Spaces didn’t seem daunting to me. She uses a set of properties files during the build process to tell Confluence what file set to use, and what ditavals they’re seeking, and then passes the properties to the ant build task. The additional wiki Spaces does mean that your URLs aren’t as simple as they could be - but in my estimation, they’re not completely awful either.
While I was researching this blog post further, Lisa also added these details about the Spaces and their individual SKU’s (Stock Keeping Unit, or individual deliverable). “Building on this baseline set of spaces, each new SKU would add 1 to 7 spaces hosting 3 to 21 deliverables, depending on the complexity of the ditaval rules and the product. Obviously, the long pole in this system is ditaval. A more ideal implementation would probably be to render the correct content based on user preferences (or some other mechanism to pass the user’s context to the engine for runtime rendition). Or, a ditaslice approach where you describe what you need, and the ditaslice is presented with the right content. Certainly innovation to be done there.“
Creating a wiki table of contents from a DITA map
She creates a static view of the TOC from the DITA map as the “home page” of the wiki. She currently uses the Sort ID assignment a DITA map XSLT transform to generate the TOC. She said they implemented a dynamic TOC based on the logical order of the ditamap by dynamically adding a piece of metadata to each topic – a sort id using a {set-sort-id} Confluence macro. The IDs are used to populate a page tree macro (the engine involved is Direct Web Remoting, or DWR… an Ajax technology). Currently, their dynamic TOC is broken due to a DWR engine conflict, which should be fixed in the next release. In the meantime, they are auto-generating a more static but fully hyperlinked TOC page on the home page of each Space. A functional solution, not great for back and forth navigation, but it shows the logical order which is pretty critical for a decent starting point.
DITA conref element becoming a transcluded wiki article
Another innovation she wanted to demonstrate was the use of DITA conrefs output as translusions in the Confluence wiki engine, so that in the wiki, the transcluded content can’t be edited inside of an article that transcludes the content. I don’t think it quite behaved the way she wanted it to, but knowing it’s a possibility is exciting. Edited to add: This innovation really does work, Lisa simply was looking at the wrong content (she admits, red-faced.)
Burst the enthusiasm bubble, there are limitations and considerations
One limitation that I observed is that when you transform the DITA source to Confluence wikitext, there are macros embedded, so when someone clicks the edit tab in the wiki, they must edit in wikitext, not the rich-text editor, to make sure the macros are preserved. In the case of the Documentation wiki, they can instruct their writers to always use the wikitext editor. But, for the Services wiki, one attendee asked if users prefer the wikitext editor, and Lisa believes they do. Someone running MoinMoin at their office said they finally just disabled the rich text editor because they didn’t want to risk losing the “cool” things that they could do with wiki text. The problem at the heart of this issue is that if users really like the wikitext editor and do a lot of “fancy” wiki text markup (like macros), then another wiki user using the rich-text editor can break the macros by saving over in rich text. Edited to add: Lisa wrote me with these additional details which are very helpful - “actually, the macros are preserved when in Rich Text Editor (RTE) mode. the problem is that it looks ugly as heck – and if the user is not techie, potentially confusing. the RTE does add all kinds of espace characters to the content– in a seeming random way - and can negatively impact the formatting in general when viewing, but it doesn’t seem to affect our macros. However, if a user wants to use macros to spiffy up the content, then wiki markup mode is definitely recommended.”
We tackled this question and then some at the January Central Texas DITA User Group meeting. I’m a little tardy in writing up my notes and thoughts about the presentation but it went really well and I appreciate all the attendee’s participation as well. We had a high school teacher in the audience and I applaud him for wanting to learn more about DITA to pass that knowledge on to high school students.
I brought along my XO laptop since I was talking about my work with wiki.laptop.org and Floss Manuals and found some more Austin-based XO fans, so that was a great side benefit to me as well.
One of Ben’s answers to the question “What does DITA have to do with wiki?” is “Maybe nothing.” Love it!
Ben introduced another the triangle of choices - you have likely heard of “cheap/good/fast, pick two.” How about “knowledge/reuse/structure, pick one.”
I have to do some thinking about that one and his perception of the limitations and tradeoffs offered by those choices or priorities. Reuse and structure are particularly difficult to pair but also give you the most payoff. Structure and knowledge are another likely pair, but it could be difficult to find subject matter experts who are also able to organize their writing in a very structured manner, and finding writers who know DITA really well and also have specific content knowledge may also be difficult to obtain. His workaround for the difficulty you’d face while trying to come up with a structured wiki is a sluice box - where raw, unstructured data is the top input, some sort of raw wiki is the next filter, and the final tightest filter of all is a topic-oriented wiki.
My take on the question is that there are three potential hybrid DITA wiki combinations, and Chris Almond at this presentation introduced the fourth that I have seen, using DITA as an intermediate storage device, interestingly.
The three DITA-wiki combination concepts I’ve seen are:
Wikislices - using a DITA map to keep up with wiki “topic” (article) changes. Michael Priestly is working on this for the One Laptop Per Child Project (OLPC.)
DITA Storm – web-enabled DITA editor, but not very wiki-like. However, with just the addition of a History/Revision and Discussion tab, and an RSS feed, you could get some nice wiki features going with that product. Don Day had an interesting observation that sometimes when you add in too many wiki features on a web page you can hardly tell what’s content and where to edit it. I’d agree with that assessment.
DITA to wikitext XSLT transform- but no round trip, have writers determine what content goes back to DITA source. Lisa Dyer will describe this content flow in the February session.
The slides are available on slideshare.net. Here are the slides that Ben Allums, Ragan Haggard, and I used.
I’ve signed up for the Give 1 Get 1 program for One Laptop Per Child, and just received the email today, November 12, 2007, with the link to the site, www.laptopgiving.org.
I read the terms and conditions with interest because I am seriously considering purchasing a laptop either for my son, who is four, or for his classroom of four-year-olds. Plus, I’ve been volunteering to help with their end-user documentation.
I’d love to buy one for every classroom at my son’s preschool but that’ll take some fundraising. I’ll boldly propose here that you can contact me if you’re interested in buying enough for a small preschool in Austin, Texas in addition to kids in least developed countries around the world.
I absolutely LOVE the spirit of the support statement. It reads as follows:
Neither OLPC Foundation nor One Laptop per Child, Inc. has service facilities, a help desk or maintenance personnel in the United States or Canada. Although we believe you will love your XO laptop, you should understand that it is not a commercially available product and, if you want help using it, you will have to seek it from friends, family, and bloggers. One goal of the G1G1 initiative is to create an informal network of XO laptop users in the developed world, who will provide feedback about the utility of the XO laptop as an educational tool for children, participate in the worldwide effort to create open-source educational applications for the XO laptop, and serve as a resource for those in the developing world who seek to optimize the value of the XO laptop as an educational tool. A fee based tech support service will be available to all who desire it. We urge participants in the G1G1 initiative to think of themselves as members of an international educational movement rather than as “customers.”
I’ve been working on documentation for the XO laptop in the wiki at wiki.laptop.org/go/Simplified_user_guide and then taking the wiki content over to an Author-it instance. I’ll write more later about a wiki-based workflow, especially with translation in mind, and we are putting a process in place. Please, feel free to edit that page or contact me if you are interested in contributing.
Personally, the most difficult part so far has been my limited ability with design and layout. I have grand visions but feel my layout skills are inadequate for a kid- and parent-friendly look within Word. Nonetheless, it is an exciting time to be a small part of such an influential project.
I’m one of the friends, family, and bloggers who is willing to help with the XO laptop. So I urge you to go to www.laptopgiving.org and put your U$399 to good use.
I’m listening in on Scott’s somewhat-famous Web 2.0 for technical communicators talk. He has given it 15 times this year already so I’m very excited to hear it here in Austin, TX at the Quadralay WebWorks RoundUp user conference. Here are my notes.
How can writers show they have highly transferable skills? What are the in demand skills?
information architecture, interaction design, modular content creation, localization and translation, document design, standards knowledge= document engineer (read Document Engineering by Robert J. Glushko and Tim McGrath). How to add value to our careers - by creating human- and machine-readable documents, whatever form they may take.
seeqpod.com - playable search engine. Files that exist and are playable. Does it actually look for keywords within podcasts and let you play the relevant portions of that podcast?
songsza.com
jott.com - what would you like to “jott” - automatic voice recording from your cell phone that can be played back.
tapefailure.com - clips of your users using your website - combine and compare patterns
Offered a case study of using for call centers using del.icio.us - have your call center people automatically add tags to items that make sense to them, then the techpubs department can see all the tags, the frequency of the items, and the different vocabulary words used for their bookmarking.
pipes.yahoo.com - visual editor for RSS feeds, bringing them together and combining them.
hosted software (Software as a Service or SaaS)
docs.google.com Google Docs & Spreadsheets (side note - I’ll be publishing my wiki talk from STC Austin using Google Docs’ Presentation tool)
thinkfree.com
zoho.com - documents, spradsheets, projects, notebook, planner, wiki, others
blogs
documentation teams or developers putting end-user doc onto blogs
wikis
interactive voice response company using wiki
parking meter company using wiki
Virgil Griffith created a wiki scanner - salacious edit site - looks for IP addresses and associates them with the company name.
DITA Storm - edit DITA pages on the web.
guided authoring - can developers write role-based documentation if they are guided to do so, with examples and guided templates so they know where content goes.
I’ve had a very serendipitous journey lately based on my podcast on TechWriterVoices and the work on the One Laptop Per Child project that I want to share. Through others listening to the podcast, hearing about OLPC, and contacting me via my blog, I learned about wikislices, and it just might be a method for DITA and wiki to play in the same sandbox.
This concept seems very apropos to the shift we’re seeing in technical publications away from books. What’s interesting is that there seems to be two directions you can go from books - wikis or DITA, crowdsourcing or singlesourcing. Some times it seems like choosing between wikis and DITA is like new school/kewl kidz versus old school/squares.
But what if there’s a way to have your wiki be the single source (also crowd sourced but with a strong guiding hand, let’s say), but to create cross-sections or wikislices of that content? This idea would essentially allow writers to write in the wiki and then either the writer or an architect would “slice” it.
There is a way to Wikislice Wikipedia already. Go to wikislice.webaroo.com and enter a subject. You can view this nice slideshow showing the basic features of a wikislice. You can even make offline wikislices available.
What’s interesting to note is that the Webaroo wikislice of “violin” is different from the one for the OLPC wikislice of “violin” and it appears that the OLPC one is more easily read by a student. Somehow the slices are customized, perhaps for the audience? I’d like to dig deeper into the guts of a wikislice. All I’ve found so far is that they’re built using regular expressions according to the Wikislices definition on the OLPC Wiki.
With the correct use of tagging in your wiki, I would imagine that you could slice the wiki based on audience, language, or content type, such as grouping tasks, reference, or concepts.
It seems like any wiki could be wikisliced, and if DITA maps are the method for the slicing, then you can get a table of contents and PDF output based on a cross-section of your wiki - a wikislice. This process is just a thought piece right now, but my hope is that working on the OLPC project helps perfect the wikislicing process so that it could be used for other end-user documentation projects.
It was one of those light-bulb-type discussions. Ideas popping and synapses firing. I had lunch with Chris Almond and Don Day this past week, discussing the potential authoring of wiki articles using DITA. We went through possible workflows, from a web-based DITA editor - to authoring in another tool and merely using DITA as an intermediary and transforming to wikitext.
If you know about DITA, you recognize Don Day as the chair of the OASIS DITA Technical Committee. Our lunch companion was Chris Almond, an innovative forward-thinking project manager. From him, I got the sense that internally at IBM, there is a perception of DITA as a technical writer-only tool to have in your toolkit. Chris coordinates and manages the authoring of IBM’s RedBooks, a very popular and technical set of documentation that are not product documentation but rather they show users how to implement a specific set of products, integrated together. He’s coordinating teams to do the scenario-based writing that applies the product in real-world situations. Many techpubs teams are striving towards use cases and scenario writing, and RedBooks are a great model for how to do it well. I know we tried to emulate it at BMC Software, and Bill Gearhart has an article about “Scenarios and Minimalism” in the CIDM Newsletter that discusses scenario and case study authoring.
Chris is trying to figure out how their current writing methodology and processes can be protected but also enhance the tools used and improve the resulting connections after the deliverable is written. Currently they engage with teams of authors to outline scenarios using mindmapping software and then divide up the actual writing assignments according to the author’s experience with the scenario. I immediately thought of JoAnn Hackos’ and Dan Ortega’s suggestions to have field personnel contribute scenarios to a product’s wiki when Chris described their process.
How do you actually empower the teams to write these wiki articles and assemble them into a useful (maybe book-like) wiki? Another question to Chris was, how do you layer an outline or table of contents on to the wiki, and then test and fold in any changes that wiki contributors make?
After at least an hour discussion I’m not sure we ever came up with the correct toolset. Or rather, there was a toolchain that could be used which is certainly do-able but not the ideal that he wanted to get to. I suppose one ideal is a DITA-based wiki with a web editor interface that would change editor strictness based on the author’s permissions. Authors who knew DITA and were most comfortable writing structured tasks, reference, and concept topics would get an XML-validating editor and authors that preferred more free-form would just use a rich-text editor that was nothing more than HTML headings, paragraphs, and lists underneath like what you use in Drupal, WordPress, or Blogger.
Suddenly it became apparent to me (but I won’t and don’t speak for Chris and Don) that some people are more determined to keep the editing quick and easy, but sacrifice that structuring and vetting step that structured authoring gives you.
This realization gives me a sense that there are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture. Also, the types of information that these authors are trying to capture are opposed in some senses. Then I thought a diagram might help.
With such an easily diagrammed moment, you’d think I’d have an answer for the process we could use for a DITA-based wiki. Unfortunately it’s not quite refined, but I feel a step closer to understanding why this process is difficult to create - because the process is paved with these tradeoffs and apparent compromises and decisions you have to make along the way.
Anne is a senior technical writer at Advanced Solutions International. Read 
