Tag Archives: techpubs

STC Intercom – themes and advice wanted

I’m quite flattered and humbled (and more than a little bit intimidated) to serve as leader on the STC Intercom advisory panel for this coming editorial year. We’re five people from different backgrounds and perspectives, tasked with preparing 10 themes for issues by August 2008. We’ve got academia, consulting, work-aday, future thinkers, and the only gap in our panel would be someone with regulatory or government limitations, er, opportunities for their content (applications for the open position, or suggestions for contacts are welcome!)

At our first informal breakfast meeting, Ed Rutkowski, Tom Johnson, and I brainstormed themes and topics for articles. Here’s our starting long list that we’ll work from and add to – and please, feel free to add to it in the comments!

Ideas

  • Agile
  • Security (such as online identity and blending that with our user assistance systems to provide online community features)
  • Biographical or semi-celebrity feature articles, such as “how did I get to be JoAnn Hackos or Jared Spool or… fill in the blank”
  • Mobile and wireless effects on tech comm
  • Gadgets and devices (get nostalgic about the Selectric? and then move towards the gadgetry of today, hardware or software? Roll up keyboards?)
  • Outsourcing, crowdsourcing, friendsourcing
  • Eco-friendly or green themes, how do you save the planet as a tech writer?
  • Career planning
  • Location awareness – cultural sensitivity but also could be online help that knows where the reader is located geographically or awareness of where a cell or mobile phone is located
  • Messaging and brand awareness
  • Collaboration
  • Virtualization
  • Future forwards thinking, not just trends and trendsetting but really out there like flying cars kind of concepts
  • Alternatives to online help
  • Social networking
  • Usability for online help
  • Audience considerations, especially in industrial settings, high risk settings, regulated settings
  • Patterns – design patterns are used in object oriented programming but they started with architectural patterns (entry way is a solution to the problem of entering a building and a room and so on.)

I’ve also identified some areas of deficit where I’m not quite sure how to fill the void. One is, there are no Gen Nexters voices that I know of in STC yet, and I’d really like to change that somehow with STC Intercom. Gen Nexters are age 18-25, just starting out in our profession. Since now is the first time in history that four generations are in the workplace, I’m striving to find those tech writers who are just starting out but have a passion for their career choice. From what I’ve read, Generation Next is made up of 18-25 year-olds (born between 1981 and 1988). Generation X (that’s me!) was born between 1966 and 1980 and ranges in age from 26-40. The Baby Boomers, born between 1946 and 1964, ranges in age from 41-60. Finally, those over age 60 (born before 1946) are often called the Greatest Generation. Please, contact me if you are of Gen Next or could tell me of someone who I could talk with for input on our themes and perhaps contributing to an issue.

STC2008 – Engaging diverse audiences with screencasts, wikis, and blogs

Two Sun microsystems writers from southern Cal
Gail Chappell gail.chappell@sun.com
Cindy Church cindy.church@sun.com

“Change is inevitable – except from a vending machine.” Robert C. Gallagher (author)

Audience – college age developers, industry-savvy developers working in the workforce coding enterprise apps

Documented NetBeans Ruby – tool for creating Ruby language programs, part of Netbeans integrated dev environment. Free, open-source software, means that contributions from the community are welcome, both for the product and the documentation

Survey by polling readers of their blog and the mailing lists – both audiences had the same expectations of deliverables – printed docs to learn at their own pace, also wanted screencasts, their initial assumption that only college age would want screencasts, but found that everyone wanted overviews and to see what it’s all about.

Assume that company-written docs are accurate, only trust community-written docs when they’re from a well known name in the industry. They’ll only trust blogs from well-known sources.

A plan that changed everything – content delivery as previous, writing style went from formal to folksy, nontraditional role, they went from writer to community member.

Previously they weren’t providing any rich media formats such as video or screencasts. If they added these, though, something had to be removed, so they scaled back on the online help. Their developers indicated that they always searched for info on the web.

Disadvantage – steep learning curve for the videos especially.

Came up with a plan for 3 writers online help, tutorials, blog, adding screencasts and wiki.

Screencast – video capture of the computer screen that includes audio narration. They used 3-5 minutes to introduce program features, 10 minutes screencasts showing how to build an application. Asked a well-known developer to narrate for them, Tor Norbye. Wanted to help build his persona, used royalty-free background music and rolling credits. Link to the page containing the screencasts – http://www.netbeans.org/kb/60/screencasts.html.

Wiki – collection of web pages that users can add and edit by using a web browser. Their “rock star” Tor Norbye contributed to the wiki. Metrics weren’t high but they were coming to the wiki. Engineering originally set it up with updates. Wanted initially to put the tutorials on the wiki, but on this official website, netbeans.org, that’s where all the other tutorials were being placed. Use the wiki for drafts of doc instead of uploading tutorials. One way to use wiki was delivering info quickly, didn’t have to be perfect or templatized. Also used the wiki to post drafts, then emailed user forum to let them know they could review it. Once it was reviewed and vetted, transferred it over to the main website instead of the wiki. Feedback from customers on docs they’d like to see – wish list of docs, requested that the community help write those docs as well. They also searched the internet to find info in blogs, and pointed to those blog entries that were helpful.

Blog – Insider scoop from the tutorial divas, mix technical and non-technical topics, such as interviewing a student ambassador and posting vacation pictures to the blog. Include tidbits from tutorials. tips and tricks – top three ways to install on linux, tried to post at least twice a week.

Traditional docs – using company templates and guidelines. Short, focused tutorials, containing steps, screenshots, and code. Went to minimal online help. Addressed needs of global audiences and those with limited bandwidth, unlike screencasts. Kept online help to real basics, got rid of “duh” information that people could figure out on their own. Thought about posting online help files on the web, but ran into immediate problem, when they searched, they hit help topics, but users didn’t necessarily want that. Embedded feedback mechanism on all help topics, webform per topics, when it sends, it goes to every writer on the Ruby project.

Q from audience – you’re doing open source, but what about licensed software? One A from the audience, Extranet with support login IDs.

Still maintained formal style, but only for tradition docs.

“Let the authors be free to use their own individual writing style” from the developer survey

With the wiki and blog, it was much less formal, adhered to company branding requirements, but bypassed editorial review and used conversational writing style and own voice. They became trusted names as well.

Final big change – from writer to community member – new hats – writer, managing editor, first responder, community personality. When they had questions, they’d ask the community forum, which was staffed by both the Sun employees and the community members, they’d get answers quickly.

They’d search the web once or twice a week and post new news to the wiki, to keep the front page of the wiki dynamic and updated. Could provide a more varied doc set.

They enjoyed “first responder” best of all – getting the emails responded to within 24 hours of receiving it. If they had to ask an engineer, then the user got feedback right away that they’re working on it. Writer knew they were responsible for the areas for which they wrote the doc.

Looked at their doc formats and tried to figure out how to get an online identity – included their names on the tutorials, on screencasts closing credits, the blog, and the wiki. Also have their pictures and bios online.

Five major challenges –
convincingdetractors – many writers didn’t want to change the way they were presenting information
overcoming steep learning curve esp. for screencasts – Tor didn’t want screencasts done on camtasia, wanted them done on Mac. Also a tutorial doesn’t make a good script for a screencast. Also had to record at least twice.
Finding a venue – where to upload the screencasts, didn’t want to use Youtube, not a large enough frame size. NetBeans TV is where they ended up posting. August started posting, there’s a rating system on NetBeans TV, plus post related docs and screencasts. Wanted quicktime format movies. So used mediacast.sun.com, only Sun employees can post to it, but anyone can view the posts.
Watchdogging the wiki – all they do now are quashing inappropriate content. If a community member has posted a tutorial and it becomes outdated, what to do? Pull it, ask the community member to update it? Mark it as “not vetted/warranted,etc?”
Combatting shyness – we’re accustomed to writing in anonymity, but had to put up pictures and their name. Made a blog that was a group blog, could encourage others to write.

Three tactics for analyzing the success of deliverables

Omniture SiteCatalyst – looks at daily unique visitors
socialmeter – determine number of social sites that link to their pages. (Hey, cool, my blog’s social meter score is over 1,200.)
User comments and ratings – part of their help system and the wiki.

Milestone releases last summer, after five months, analyzed. What succeeded, where to improve.

Screencasts – most popular was 1000 views a day, 2nd most popular was 240 views a day. 160,000 downloads from mediacast, had to open extra ports to handle the downloads. Going forward, have dev record screencasts on their own, and writers will produce screencast. Tools – IShowYou, Snapz pro. Finalcut pro for editing (“like using a sledgehammer to pound in a thumbtack”). Keycastr to record the keyboard shortcuts that appear in the upper right-hand corner of the screencasts.

Most popular tutorial was actually the written version of popular screencast with 180 downloads a day. Installing and configuring ruby support averaged 130 visits per day. Socialmeter score of 314 by end of five month period – del.icio.us, furl, digg, google links, reddit, shere, spurl, Technorati links.

Advanced tutorials got far fewer hits
only one comment on online help pointed out missing/incorrect info
averaged one comment a day on tutorials, esp. getting started.
change and Ruby programming language changed their tutorials, user feedback made them aware. Fixed tutorial, blogged about it when they fixed it.
Blog results – more than 300 visits per day, top 10 blog entries are technical topics, most read were from previous project. Good for short topics, testing tutorials, building relationships with the community, and polling customers.

Wiki results – added new, edited existing. wiki daily unique visitors 65 on front page. 22 on Installation, 6 hits per day on documentation area, averaged only 11 hits per day on the whole wiki. Socialmeter score was 146, lower than screencasts. Low community participation. Need to make official web site and wiki work better together. While their wiki had only 3 community-produced docs, Netbeans.org just attained 150 community-contributed docs. Will do usability on the front page of the wiki. Want to set up a rewards system and have a free giveaway – tshirts for tutorials.

Projects on the horizon
Vodcasts – screencast on iPod with RSS feed to iTunes. Quality is degraded, though, so they would produce file specifically for vodcast.
Books – Still a lot of value in a book; quote from a developer “to master something as complex as a new language, I want to be comfortable on the couch with no computer in sight”
Next-gen screencasts – interactive, want to stick with Mac and native OSX. Thinking of screencasts in another native nonEnglish language. They also make sure there’s a written doc that matches the screencast to make it accessible. They also show keyboard shortcuts during the screencasts. Youtube is a good venue for just faces, interview with developers at a Sun conference in Sydney.
Videos
Wikipedia – want a page that describes the technology they’re working on.

Regardless of age or experience, a developer thinks like a developer.
Screencasts, wikis, blogs and traditional written documents meet the needs of developers across generations, from college-aged developers to industry-savvy developers.
A developer can never have too much information.

… and curiosity keeps leading us down new paths.” – Walt Disney

STC2008 – Writing as an Asynchronous Conversation

I had high expectations for Ginny Redish’s talk at STC this year, and she did not disappoint. It was wonderful to have my ideas about conversation and technical communication vetted and couched in academic terms such as linguistics, pragmatics, and so forth. Here are my notes. Please let me know if this is useful to you and if you have any suggestions for my liveblogging skills.

Writing as an Asychronous Conversation
Ginny Redish

Our conversation is synchronous – at the same time.
The term Asynchronous means at different times.

Book = Letting Go of the Words

Conversation as a theme for all we do as technical communicators.

Asked – how many of you have a different degree other than technical communication? Nearly everyone raises their hands. Ginny’s background is linguistics.
Exploring – all the new social media ways that technical information is shared through written conversations – participatory media as discussed by Harold Reingold in the keynote session

Boundaries – not discussing Skype or VOIP (it’s synchronous and it’s not written, it’s voice), not talking about IM or chat because it’s synchronous, not talking about AI (computers talking, Eliza).

Think about a recent trip to the web – why did you go, what were you doing? How much was that a conversation?

Caroline Jarrett’s model of forms – appearance (looks), conversation – jam in the middle of the sandwich (how it talks with the user), relationship (does it set up trust, credibility?)
We’ve been writing these for a while… UI, Error message – dialog boxes are conversation

The conversation is often prefaced with “How do I?”

Think of conversation as turn taking – it’s not always explicit, but you’re anticipating questions – implied conversation. Example – “What’s in the box?” – Hardware includes a SIM card (implied next question, “What’s a SIM card?” placed in a textbox) Last question after listing all the contents of the box, “Missing something?”

Another example – bulleted list “If you want to do this, here’s how” It’s a conversational way to do things, and there’s research to show it. Doesn’t have to be questions, can be “If/Then.”

Not this – Issuance of a TOP command results in a line zero condition.
This! To go to the beinning of your file, type TOP and press Enter.

Linguistics research on pragmatics (language in use, the context) The context may cause the utterance to have a meaning. Speech act theory – in many cases the spoken words are not taken literally, but you must understand the meaning behind the words.

4 maxims of conversation from Wikipedia – Gricean_maxims
If these are violated, cooperation/agreement declines.
Deborah Tannen – sociolinguist, misunderstandings because of the meta message behind the message – cultural, gender understandings.

Do not make your contribution more informative than is required – minimalist principles.

Person 1 – I’m low on gas.
Person 2 – There’s a station around the corner.
Assumptions – they’re in a car, that it’s a car fuel that they’re talking about
What if Person one responds, I know that, but I left my wallet at home – repairing the conversation. In writing, we have to anticipate the conversation so well that we think about how the conversation is interpreted and the user’s next question and response.
Person 2 has reason to believe that the gas station is open and is selling gas.

Next conversation – a good one or not? NO
To exit the program, type Quit and press Enter.
Be sure to save your files before you do that.
Actual example from a manual that Ginny has reviewed.

Implications of following Grice’s maxims:
know your users, what they know, and their context
think about interpretation (write so as not to be misunderstood)
realize that context changes
turn taking – give and take turns

Examples from Caroline Jarret, open university web forms
points – what are points, do you need them to graduate or to enter the program?

Pat Sullivan, Purdue University – dissertation from Carnegie Mellon, read only as far as what they thought would solve the problem.

Write with first things first – context first.
Approved fumigation with methyl bromide at normal atmospheric pressure in accordance with the following procedure, upon arrival at the port of entry, is hereby prescribed as a condition of importation for shipments of yams from foreign countries. (paraphrased)

Give and take in conversation
are pieces of info right sized for what user wants a s a chunk – too much (fire hose, wall of words), too little at a time (have to click Next too often)
are questions grouped logically

LiveValidation example:
Say “hello” to LiveValidation (form box)
if you don’t type fast enough, webform responds “How come you’ve not said ‘hello’ yet?”

CHI to HHI? Should it be not computer-human interaction but human-human interaction through the computer?
Tee hee, right when Ginny asked, are information products going away? Her slide show went on screen save mode.

More people go to Google than the user manual – should you spend resources contributing to the customer forum instead of expecting users to go to the manual?

Future of information for students – ? textbooks replaced by spectrum of web pages

Think “conversation.”
write conversations.
Facilitate conversations.

Putting content into context in a wiki – especially in a large environment

An interesting read on the front page of wordpress.com of all places. I enjoy random clicking, and this one came up with a great commentary on the difficulty of using a wiki to get how to information.

From Learning about Second Life from Google:

Over at SL, the main source of information is on the WIKI, which in my opinion has some great information but because Linden primarily lets the users run the show isn’t as helpful as some sort of information clearing house. Trying to sort out how to sculpt, for example, is an exercise in total frustration. There are some wonderful tutorials, but SL does nothing to properly aggregate and put these tutorials into context.

I wonder what Second Life could do to properly aggregate those tutorials to meet this user’s needs? I suppose long-time wiki writers would answer: use categories and encourage tagging, while looking out for orphans. Any other ideas?

I got a great question from Tom Johnson of I’d Rather Be Writing:

I’m just wondering if you have any thoughts on the WordPress Codex, http://codex.wordpress.org/Main_Page. Yesterday I was looking at this Codex wondering what to make of it all. I think I want to be a contributor, but there are so many topics. It’s chaotic. The organization is like a maize. I don’t know if I should go in there with a wrecking ball and rennovate, or not. Probably 25% of it is outdated. What happens to those outdated pages? Will I offend people if I just delete things that are outdated?

Can you recommend a book or strategy for making sense of massive wikis? Where should I start? I spent a good hour editing a page of it last night that I considered critical. It’s then that I realized this is a huge project and I have no sense of direction. Any insight you can give me would be much appreciated.

With the OLPC wiki, David Farning on the Library list went through the wiki and said he found these categories. It’s quite an accurate content analysis from what I’ve seen, so I was impressed. At the same time, it also helped explain my initial wonderment at how to wrap my arms around the entire wiki – and in fact, it is barely possible to do.

Content
1 Philosophy
2 Contributing
3 Creating
4 Curatoring

5 Projects
Deliverable
In progress
Ideas

6 Management

Once David came up with these categories, he then asked SJ Klein, director of community content and long-time Wikipedian, if he thought the wiki needed structure.

SJ said that the wiki is purposefully without hierarchy – flat, especially for projects, to not force a parent or sibling sense for projects. He also said, however, if you have a specific tree hierarchy in mind, feel free to develop the idea in some temporary space.

So, when working on a large wiki if you have good organization ideas, set them up, and then ask for community feedback. Seems like an appropriate approach to a large wiki.

Other ideas for starting out in a large wiki environment:

While it might seem like it’s a question similar to “how do I get started on a huge writing project?” in my experience, wiki editing has some subtleties due to the collaboration and community vibe already present behind the pages. You have to work harder to figure out that vibe, and then determine your course.

For new people, there’s the whole question of getting a feel for the community so you can start to answer “who am I going to potentially irritate by editing this” and “as a newbie do I have the confidence I’m right?”

So, knowing your role within the wiki community is a first step. You might take a while to get to know who’s there, what their roles are as well, and where you might best fit in. Introduce yourself with your profile page, following the WikiPattern, MySpace – see http://www.wikipatterns.com/display/wikipatterns/MySpace.

Just like a newbie on a writing team, find out if there’s some scut work that you can do to get your feet wet, if needed, to gain the community’s trust.

Deletions are going to bring much more wrath in a wiki situation, I would guess, so they seem risky to do to start out. If you do think something needs deletion, message or email the original author or the big contributors and ask if it’s okay to mark it for deletion. Then, mark it, and hope that someone else (a wiki admin) determines if it should be deleted.

Start small, like tagging, or applying templates. That’ll help you get a feel for the bigger picture.

Let us know your ideas for wrapping your head around a large wiki, we’d love to hear them.

Wiki as online help source

A response to the question, Wiki-to-Help? on the Help Authoring Tool Yahoo Group.

One of our test engineers (and the lead developer of our company wiki) just approached me with the idea of using our company’s internal wiki as the central repository for all company material and using it to generate online help.

I’m following the discussion with interest. I, too, had a similar question asked of me from a developer when we were working in an Agile development environment at BMC Software. In that case, which was at least three years ago, the matchup between the wiki HTML output and the HTML output I needed for our particular help system just wasn’t a good fit. But today, there are better pairings, input to output. I think it’s feasible to go from a wiki to an online help system. It really depends on what output you need, and what you’re willing to do to ensure that the wiki source is worthy of publishing (tested, vetted, trusted, and so on).

I’ve been working on wikis as source for manuals, where the output is a PDF file. In general, yes, wikis are a little clumsy to work in for authoring. For example, some wikitext doesn’t understand that you want a numbered step list with images in between each step and that you want the numbering to continue after each image. So if you’re accustomed to a nice HTML authoring interface, a wiki authoring interface will “feel” like a step about 10 years back in time. 🙂

On the more interesting issue, the cultural issue (or the career issue, depending on how you think about it), I think the basis of most arguments against using wikis as source is the fear of loss of authoring control. See wikipatterns.com for the many anti-people patterns that wikis tend to foster if you don’t take steps to avoid them. I especially liked one of the responder’s comments to the list that he didn’t want to become an editor for a wiki. I think he’s right – that “magazine editor” is one of the roles you could take as a wiki-based author. You could also consider your role to be “community director” if you think you can motivate others to contribute to your wiki that will eventually be the help system. There are different roles that will evolve, and it’s up to you to figure out what role might work well in your environment (or if it would work at all). I wrote up a blog post last week about determining where your role as technical writer is most valued in the company, and building from that role.

I believe the cultural or social difficulties are the more difficult hurdle – you have to ensure that the community surrounding a wiki (those that can and will edit) is a group that is willing to work together and collaborate towards the common goal of publishing a customer-facing help system from the wiki. In a SXSW Interactive session titled “Edit Me! How Gamers are Adopting the Wiki Way” one panelist said that a core group of five editors on a wiki may be the best practice for the size of the group. This type of small number is represented and described in the 90-9-1 theory on wikipatterns.

A solution that might help you wrap your arms around the wiki as source is to set aside only one area or category of the wiki as the articles from which the online help gets generated. Again, without knowing the wiki engine you’re working with and the types of output you’d require, it’s difficult to know if a “wikislice” solution could help in your situation.

Anyway, I could go on and on (and I believe I just did go on and on) about using wikis as source for end-user documentation. I’m pleased that Sarah O’Keefe has just published a white paper titled “Friend or Foe? Web 2.0 in Technical Communication” that should be helpful as we begin to define our roles in each company and how we integrate user-generated content with our own on our product’s web sites.

I hope this information can help you build an argument for or against the use of wikis as source for online help. Please let me know the eventual outcome, and I’d love to hear your thoughts on my response.

Technical writers and conversations

I’m continuing my musings on connected conversations and tech pubs since there were such great comments and conversations going on with it.

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.

Examples of content providers blogging for customers

Sarah O’Keefe wrote up a nice summary of the WritersUA Pundits Panel, and Bogo Vatovec (of Bovacon)  made a statement something like this:

Introverted technical writers will not be writing help any more and will be replaced with experts moderating support forums. … Technical writers can no longer afford to hide in their cubes, they must go out and become experts and talk to the users.

I left a comment on her post that I see a similar future for our profession, although I do not have a value placed on introversion versus extroversion – likely introverts make perfectly good community managers and forum moderators since they can do that from their desks for the most part.

But, it does take some bravery to put your real personality online. I’ve found that a few of us are doing that – going from technical writer to blogger writing directly to customers.

While many of us blog to an audience of other professional writers, there are technical writers out there who are blogging to their end-user audience. Here are two examples:

  • Another example is Dee Elling’s blog for CodeGear users. This entry offers a great example of a real conversation with customers. I applaud her bravery (and emailed her to tell her) in facing these sometimes abrasive responses with a sense of customer service and helpful attitude. She doesn’t always have a good message to bring (they are working furiously to give their customers more code examples which we all know is time-consuming and difficult). But she brings a message directly to customers anyway.

Is anyone else talking directly to their customer base with their blog? Consultants in technical writing and content management are definitely talking to current and potential clients – Palimpsest is Scriptorium’s blog, The Rockley Blog, The Content Wrangler, and DMN Communications to name a few. But what about conversations with end users? I’d love to see more examples.