just write click

Next week I’m presenting at the Alamo STC Chapter, giving a talk titled “A Technical Writer’s Role in Web 2.0 — Wiki-fy Your Doc Set.” It’s at the Igo Library in northwest San Antonio and you’ll want to refer to their website for directions. It’s Tuesday February 12th with the presentation starting at 7:00.

I plan to update the presentation from the last time I gave the presentation at the Austin STC chapter and I’ll post the slides to slideshare when they’re ready. I’ll take it out of Google Presentation format and go with PowerPoint since the 800 x 600 display was pretty dismal using Google Presentations. It’s too bad because sharing that presentation was so easy.

The week after next on Wednesday February 20th, the Central Texas DITA User’s Group is continuing the wiki panel discussion we started in January with three more speakers talking about their wiki experiences, including one wiki that uses DITA as source. Here are the presenters:

• Lisa Dyer, Lombardi Software
• Michele Guthrie, Cisco
• Alan J. Porter, Quadralay Webworks

The networking starts at 7:00 with the panel starting at 7:30. It’s at the Freescale campus on Parmer and directions are available on the DITA wiki. I’m looking forward to this presentation as an audience member as well to learn about more wiki best practices and DITA conversions to wikitext.

Next week I’m speaking at our local Austin STC meeting about wikis and technical documentation. Here’s the relevant information if you’re in the area. Interestingly, Scott Abel of The Content Wrangler is giving his Web 2.0 talk at the Quadralay WebWorks RoundUp that afternoon as well. It’s a Web 2.0 world for tech pubs folks in Austin next Tuesday. Hey, I just noticed that Quadralay has started a Blogs area on webworks.com, great!

Here’s the logistical information for the meeting in Austin next week:

A Technical Writer’s Role in Web 2.0 - Wiki-fy Your Doc Set

Anne Gentle, senior technical writer at ASI International and blogger at http://www.justwriteclick.com/

How can a wiki be used to build user-centric, user-maintained technical documentation sites that offer thorough and accurate technical information? More than two years ago, I issued a challenge to my colleagues to send me examples of technical documentation in a wiki. I was skeptical that wikis could be used in a meaningful way for technical content. Through tips from coworkers and word of mouth, I found several wikis to study for the types of content that can be placed in a wiki and try to derive best practices for when, why, and how to start a wiki.

Where: Commons Center on the J.J. Pickle Research Campus, Austin, TX

It’s near the corner of Braker Lane and Burnet Road. There’s a map of the campus at http://www.utexas.edu/commons/maps/index.html.

When: Tuesday, November 6, 2007

6:00-6:30 PM: Networking

6:30-7:30 PM: Program

7:45-9:00 PM: Networking Dinner at the California Pizza Kitchen at The Domain

I’d love to see you there!

I’m happy to report that my article about using wikis for technical documentation was published last week in the STC Intercom.

A PDF my article is available for anyone to download, STC member or STC non-members alike.

I’ll be giving a presentation about wikis for technical documentnation to the STC Austin community on Tuesday November 6th at the Commons Center, which is located at 10100 Burnet Road, Austin, TX 78758, near the southwest corner of Burnet Road and Braker Lane on the University of Texas J. J. Pickle Research Campus. Map

If you’d like to see what else I’ve written about wikis, take a look at the articles in my wiki category, or check out this list from my talk.bmc.com blog.

So many people helped me with the Intercom article. Kelly Holcomb is an excellent editor and helped me with it in her small amounts of spare time. Emily Kaplan read an early copy and also helped me sort through my notes. Michael Cote has sent me interesting items about wikis that he has found and also constantly tags useful information in del.icio.us. Diane Fleming was investigating wikis on her own, asked me about them, and then gave me great feedback on an early copy of the article. Tom Johnson was extremely positive when he first read it as well. I spoke with Dee Elling who had two excellent experiences to talk about in her interview with me. Harry Miller had a podcast interview with Molly Bostic, the PM on the MSDN wiki team, that was very informative.

It takes a community to write about online communities. Thanks, everyone!

Here’s a link to my latest article on Hyperviews Online, the newsletter/blog for the Society for Technical Communication Online Special Interest Group (STC Online SIG). It’s called Using a Content Management System (CMS) for your STC community web site.

The STC Austin chapter is re-designing the community website, and I volunteered to help. We started researching CMS use and I found that quite a few sites were using WordPress, so I emailed the webmasters to learn more. The article is a result of that email survey where I learned more about WordPress as a CMS.

I’ve been researching an article for STC Intercom about wikis and technical documentation as discussed in my previous post. In about two years of my interest in the topic, I have only discovered a handful of examples of wikis used for end-user documentation for a technical product. And sometimes I even stretched the term “technical product” to include all of eBay. Heh.

If you’re also interested in wiki research, I have also been compiling bookmarks of blogs or websites that comment on wiki use on del.icio.us too at http://del.icio.us/annegentle/wiki.

Anyway, here’s a list of the ones I’ve found as good examples so far, but my criteria are loose and fast, such as recognizable products or geeky products. I’m sure there are more, and this list of the top 57 wikis based on popularity offers an even longer list.

• Apache wiki: http://wiki.apache.org/
• Adobe Labs: http://labs.adobe.com/wiki/index.php/Main_Page
• eBay: http://www.ebaywiki.com/
• Motorola Q: http://www.motoqwiki.com/
• MSDN: http://www.msdnwiki.com/
• Quadralay: http://wiki.webworks.com/FrontPage
• SplunkBase: http://www.splunk.com/base

But instead of soliciting more examples, I want to ask a few more questions myself. How many of these wikis would I use to get an answer to a question? Probably all of them. Now, how many wikis have I contributed to? How about you? If you haven’t ever contributed to a wiki, why not? If you have, tell us which one, and what motivated you to contribute?

I’ve been doing some research for an article for the STC Intercom based on the interview I did with a friend of mine who does maintenance on the MOTO Q wiki. The article will come out this fall and I can’t wait to see if any rousing discussion appears on the STC forums. In the meantime, I want to continue to blog about wikis because I want to continue to research their use in the technical publications world.

I have had an interest in wikis for technical documentation for a couple of years now. There are a couple of good discussions on wikis for technical documentation from February 2007 on Tom Johnson’s I’d Rather Be Writing Blog as well as The Write Time blog. Tom’s post talks about using wikis to help with the documentation process. In response, there’s a wonderful entry by Lars Trieloff about exactly how a writer uses wikis for technical documentation.

While my STC Intercom article doesn’t talk about the internal wikis I’ve used for documentation tasks, as an Agile team member, I did find that the wiki housed information while development was ongoing and I also edited pages to keep them updated as I discovered something in the code that didn’t match the wiki.

It’s funny, in an early blog post I wrote on the internal blogs at BMC I said that I did not see how wikis would be used successfully for technical publications. I have since changed my once low opinion of wikis but I still see them supplementing other documentation, not substituting completely for technical documentation. I’d welcome discussion about wiki as standalone or supplemental end-user documentation. What do you think? Should the merits of wiki for certain products win out as the exact right documentation for that particular product especially one either related to an Agile methodology or social media? Or are wikis relegated to an upgrade to the customer support forum with a kludgey way of entering the information and no good method for outputting an information deliverable worth reading?

If you’re in Austin, you’re welcome to attend the Society for Technical Communication meeting where I’ll be moderating a discussion about best practices for documentation.

I’ll be moderating a discussion Tuesday night at one of our Society for Technical Communication chapter meetings. I found this article, “Tech writers as sales reps? Interface Software’s award-winning docs boost brand, revenues, and customer satisfaction” and thought it has some great points but I really wanted to get the opinions of others in tech comm to see how well it holds up in reality. The title sure promises a lot, doesn’t it? It’s an excellent read.

Our meeting announcement made it into the Austin American Statesman in their “Tech Week” section, so that’s exciting. Here’s their announcement: The Society for Technical Communication will host a panel discussion on the practice of technical communication. Speakers will be Wendy Shepperd, information development manager at BMC Software Inc.; John Gough, principal technical writer for Troux Technologies Inc.; Cathy Mallet, information developer at Motive Inc.; and moderator Anne Gentle, information developer at BMC. 6 to 8 p.m. MCC, 3925 W. Braker Lane. Free. www.stcaustin.org.

If you’re local to Austin, come on over and listen in on our discussion. I don’t expect we’ll figure it all out in an hour or so, but these articles and topics sure do get folks like me thinking. Feel free to chime in here on the blog as well about your opinion on these best practices.

Summary of best practices

#1: Create a healthy workplace.

#2: Understand the value of good documentation.

#3: Use documentation to gain an edge.

#4: Have a reasonable ratio of writers to developers.

#5: Place technical writers somewhere sensible in your org chart.

#6: Keep technical writers in the loop on development plans.

#7: Encourage technical writers to meet customers.

#8: Use customer advisory boards to get feedback on documentation.

#9: Make the right tradeoffs.

#10: Pick the right medium for each deliverable.

#11: Provide print for those who need it.

#12: Give your writers the right tools for the job.

#13: Try out conditional text.

#14: Explore single sourcing.

Bonus tips

Bonus tip #1: Hire writers with the right stuff.

Bonus tip #2: Hire writers who ask smart questions.

Bonus tip #3: Don’t get hung up on tools.

Bonus tip #4: Provide lots of feedback.

Bonus tip #5: Insist on timely reviews of drafts.

Bonus tip #6: Enter publication competitions for feedback.