I'd Rather Be Writing » WritersUA

Conferences I’m Attending This Year

Tom Johnson — Tue, 28 Feb 2012 14:55:52 +0000

I’m attending three conferences this year: Confab, the STC Summit, and Lavacon. Why did I pick these conferences, over others?

Ben Minson and me at a previous STC Summit

I attended Confab’s inaugural conference last year and felt it was a good fit for my web publishing role at work. Although my job title is “senior technical writer,” I spend about 60% of my time being a web editor for LDSTech. LDSTech has a blog, wiki, and forum, and in many ways, it’s the communication/awareness arm for our IT group.

Confab is a perfect conference for anyone involved in web publishing. I’m still wrapping my head around content strategy. Last year I learned that it means a lot of different things to different people. Mainly, whatever techniques you employ to give your content an edge is a content strategy. More than anything, Confab seemed like a web publishing / marketing / content strategy conference. Only a few technical writers were there last year, and you probably know them all (Scott Abel, Rahel Bailie, Ann Rockley, and a couple of others). Yes, only about five technical writers out of hundreds of attendees). Just like 2011, the Confab conference sold out early again this year. (I don’t pretend to understand conference dynamics, but their staff seems to openly defy the law of supply and demand.)

When I’m not being a web editor, I write help material. Most of the applications I document are small in scope. I never document anything that has 1,000 topics or more. I remember once talking to Joe Gollner at a conference. He works on projects that have hundreds of thousands, perhaps even millions, of topics. I can’t imagine documenting anything so vast. I guess this means I’ve become more of a technical writer involved in lightweight projects. That suits me fine, though.

I initially wasn’t going to attend the STC Summit this year. I submitted a proposal, but then changed my mind about the conference and withdrew my proposal. Because I helped review proposals for one of the tracks, I received a discount on registration. Despite canceling, I still had a nagging desire to attend the summit. Not so much for the education sessions, but because it’s a conference that all my professional friends attend. It’s the epitome of #techcomm. Some training budget funds opened up last week, and I managed to squeeze it in.

I’m not staying at the $200-a-night conference hotel, though, especially when that price doesn’t even include Internet. The point in attending a conference or visiting any city isn’t to abscond oneself in the hotel watching cable and lying on luxury pillows. The point is to get out and interact. I love walking around the city, exploring new places. I enjoy getting out of the hotel perimeter, past the point where every store caters to out-of-towners at hotel prices. Also, my travel budget isn’t so vast that I can afford to stay in fancy hotels and attend multiple conferences a year.

The trouble with attending Confab and the STC Summit is that they take place two weekends in a row. This only goes to show that the Confab conference planners aren’t targeting technical communicators, or that too many competing disciplines have conferences in the same short period of time.

The final conference I’m attending this year is Lavacon. I’ve never been to Lavacon, though I’ve helped out with the website for it. Jack Molisani asked if I’d like to present, and I got to thinking how nice it is to get out of the office in the fall, outside of the regular conference season. And yes, I do have a topic percolating that I’d like to present about: crowdsourcing writing tasks. The Portland venue makes the conference even more appealing, since I’m a northwesterner myself, born in Washington State.

Apart from these random details about conferences, have you ever wondered about the deeper reasons why we go to conferences? What draws us to attend? Perhaps it’s because conferences hold the promise of an idea. Put together hundreds of professionals from the same discipline in a room, and all kinds of innovation should take place. Why doesn’t more innovative thinking happen? Are we stifled by hearing the same voices again and again in presentations? Are we distracted more by the schedule than by the point of the gathering? Do we not attend with enough questions and problems to solve?

Last year my former colleague Derek came back from WritersUA and said the conference consisted of many excellent presentations and information. Like what, we asked? Tell us what you learned. Unfortunately the details of that conversation never materialized in much depth, which makes me think that the takeaways from conferences might not be any notes you write down from presentations, nor the people you meet during all the “networking opportunities,” but rather an igniting of thought about your discipline and how to move forward in your professional endeavors. Derek returned more determined than ever to implement an enterprise-wide authoring strategy.

Although I’m not presenting much this year, I do lean towards a preparation model that may not be entirely sound. Whereas most conferences invite speakers who are recognized experts on topics they’re familiar with, I think you should submit a proposal based on a topic you want to explore for the year. Then present your findings about your exploration at the conference. The conference acts as the culmination of months of research, experimentation, and thought about the topic.

I did that last year with the topic of findability at the Summit. Knowing I would be presenting on the topic motivated me to keep it foremost on my radar, and I explored the heck out of it, writing more than 40 posts on findability. But because of the difficulty of the topic, I never reached the triumphant conclusion that would lead to a knockout presentation. And not having that triumph in hand led to enormous stress as the date of the conference approached. Good stress, but perhaps more than I care to repeat.

This year, with just one topic on the agenda — crowdsourcing writing — I am taking it a bit easier. I’m not a total expert on this topic, but I’ve been wrestling with it for the past 8 months now. I’ve made more progress than many, and I know how to do it, just not how to pull it off on a grander scale.

I look forward to interacting with you at some upcoming conferences. Is there a conference I’m missing out on? I’d love to hear about it. More than interacting, though, I’d love to learn what unspoken takeaways you get from attending conferences.

Blog Sponsors

Why don’t technical writers use wikis — or do they?

Tom Johnson — Fri, 24 Feb 2012 07:26:50 +0000

The following is a guest post by Sarah Maddox, a technical writer at Atlassian.

Sarah Maddox

In a recent conversation, Tom mentioned that he’s been pondering this question: “Why, in a time when collaboration is more important than ever, do wikis still remain mostly unused as a help authoring tool in tech comm departments?” Tom asked me to join his ponderings and write a guest post on the topic. Thanks for the invitation and the thought-provoking question, Tom!

I started by thinking about the question itself. Do we know how many people use wikis as a help authoring tool, and what do we mean by help? For this post, let’s say that “help” means technical documentation in general, which I think is the thrust of Tom’s question.

Is it true to say technical writers don’t use wikis?

Serendipitously, two bits of news appeared just as I was about to put my ponderings to paper.

The first was a guest post by David Kowalsky on The Content Wrangler: Collaborative Authoring and Communication Tools Help Writers, Editors, SMEs Work Together. The post discusses a number of collaboration tools, yet wikis get only a very brief mention: “Wikis are becoming more widespread.” That’s it.

So, that post lends strength to the surmise behind Tom’s question. Wikis are only barely in the picture.

Then another bit of news popped up – the results of the 2012 WritersUA Skills and Technologies Survey. When conducting the survey, WritersUA provided a list of popular user assistance technologies and asked the respondents to value the importance of those technologies in their current development efforts. The technologies section of the survey shows that 28% of respondents rate wikis very highly.

28% is not to be sneezed at.

One respondent noted:

Ask again next year and the landscape will have changed dramatically. We intend to migrate from Webhelp to a wiki/kb delivery model and I can’t wait!

WritersUA also provide details of specific tools, where wikis are mentioned quite a bit too. Try searching the page for “wiki” and “confluence” (because the latter is mentioned without the word “wiki”).

Rephrasing the question asked in this post

Based on the WritersUA results, I’ve changed the question slightly. Instead of asking why wikis remain mostly unused as a help authoring tool, let’s ask, “Why don’t more of us use wikis as a help-authoring tool?” It’s an excellent question to address in a blog post. There are likely to be some passionately-held opinions and some great stories around the use of wikis, experimentation with wikis, trials and tribulations as well as thrills and conquests. Bring ‘em on, folks.

So, why don’t more of us use wikis as a help-authoring tool?

I think the crux of it is this: each type of tool makes one set of functionality easy, and supplies other sets of functionality via add-ons or processes that are less comfortable.

Wikis excel at collaboration, notifications and monitoring of updates, integration with other web apps, sharing content, and social features like networks of colleagues and status updates. They also provide instant gratification, by publishing updates as soon as you click save. (That’s the default behaviour, though in some wikis you can configure a workflow to delay publication.) Wikis are great at publishing good-looking documentation with a minimum of fuss and bother.

Wikis are not so good at version control across a documentation suite, single source publishing, or topic-based authoring. They were not originally designed with that focus in mind. But there are add-ons currently available that extend the wiki functionality in the directions we need, and there are more add-ons under development that will do it even better.

Dedicated authoring tools excel at single-source publishing. The newer tools focus on structured authoring. Many of them either have their own version control system or integrate with the same source control tools used to store code. On the other hand, such tools are designed for use by a small, dedicated team. They tend to lock out people who are outside the technical writing team, due to license costs and/or technical complexity. Collaboration is therefore difficult. There is a publishing step between updating the content and making it visible to readers, which may require a delay of some hours until the documentation can be built. Some tools have introduced social features such as commenting, but the published documentation suite does not offer the people-focused experience that a wiki offers.

Can you have all the features in one tool? That would be great, and the need is there. I don’t know of a tool that elegantly satisfies all requirements. Not yet. But there are some promising developments underway. Because I’m so deeply involved in the world of wikis, I know of the excellent plugins and add-ons under development to add workflow, single sourcing and sophisticated version-control to a wiki. I’m sure that people reading this post know of the new collaborative and social features being introduced into other tools.

Weighing up priorities

Technical communication is a broad and diverse field. There are as many ways of categorising what we do as there are environments that we work in. Not surprisingly, there are as many ways of prioritising our needs too. It’s up to us to choose the tool that fits our requirements. Each tech comm team has to weigh up the priorities, based on the aims of our organisation, team and audience.

But here’s the thing: We can help by knowing the capabilities of each tool, and educating our organisations about the benefits of each.

It can be hard to know the capabilities and functionality of a wiki, and especially the capabilities that are useful to technical communicators. Wikis are constantly evolving. Sometimes additional functionality is available via installing a plugin, but it’s difficult to find that information. Or perhaps the features are there in the wiki, but are not packaged and labelled as something useful for technical documentation. For example, wiki documentation may talk about spaces, watches, notifications, RSS feeds. We need someone who is already in the know, to describe the features and show us how to use them in our workflow.

Maybe those of us who use wikis are just not especially vocal about it. Here’s a suggestion: Wiki huggers need to jump up and shout it out: Kiss my wiki.

A lot of it comes down to communication and help.

Difficulty harnessing the power of the crowd

Collaboration is a consummation devoutly to be wished. (OK, maybe not for all documentation suites, but let’s assume that we want collaborative authoring now since that’s the topic of this post.) But it’s not easy. Collaboration can be a messy business. This may be one reason why technical communication teams have not yet implemented a wiki-based solution. They’re looking for success stories. Has anyone successfully opened up the product documentation to updates by external authors? How about letting everyone in the company update the docs, or even company partners and community developers. How about the general public?

This is a broad topic. For my team, I can say that we are making it work, that it’s fun and challenging and rewarding, and that we constantly re-evaluate the way we do things to see if there may be a better way. Our documentation is continuously being updated by subject matter experts (developers, support engineers, marketing engineers, product managers and even a CEO or two). We also have a group of around 50 community authors who update pages every now and then, particularly in the developer-focused documentation.

This post would become very long if I included guidelines on how to manage the updates by everyone. Instead, here are some pointers about the things to consider:

Permissions: The tool you choose must allow you to define groups of people (technical writers, company staff members, community authors, etc) and to assign permissions to each group.
Monitoring and notifications: You must be able to subscribe to an area of the documentation, and receive notifications whenever someone updates a page.
Copyright and intellectual property: You will need to display a suitable copyright license (we use Creative Commons by Attribution) on all the pages, so that contributors and readers alike know their rights. It’s also a good idea to ask contributors to sign an agreement, signifying that they understand the intellectual property arrangements for the content that they contribute. Our agreement is based on the Apache Contributor License Agreement.
Encouraging people to contribute: It’s safe to say that you won’t be deluged with updates. Instead, invite people to update the documentation and keep telling them how much you appreciate their contributions. The experience is rewarding and enlightening. Every day you’ll learn new things about your readers and the way they use your products.
Style guides, templates and structure: It’s a bit of a balancing act. Too much structure can deter contributors. Yet everyone appreciates some guidelines. Templates are very useful, especially in getting rid of that dreaded empty page that needs filling. A light style guide, informative rather than prescriptive, is useful to external as well as internal authors.

The above points are some of the things to consider when allowing other people to update the documentation pages. There’s more to think about when you allow people to add comments to the pages. For example, the volume of contributions in comments can be overwhelming – people are more likely to add comments than to update a page. You’ll need to ensure that management understands the number of people required to handle such input, and the different types of comments that you will receive. In our experience, most comments are calls for help rather than points about the documentation itself. It’s therefore useful if the support team and developers can help respond to the comments too.

The most rewarding thing of all is that people help each other. Someone asks a question, someone else answers, and everyone benefits, without the technical writers needing to intervene at all.

Customisable look and feel

Technical communication teams need to add a brand to the documentation (logos, colours, fonts). They may want a tripane help system or something that looks closer to a website.

In the early days, all wiki documentation looked the same. Bland, black and white with blue links, and if you were lucky a left-hand navigation bar with a table of contents. Above all, there were no rounded corners to be had for love nor money.

Things have moved on, and wikis allow a fair bit of customisation via themes (skins), CSS, replaceable logos, and more. But I think many people still hark back to that era of prosaic look and feel when they hear the word wiki. Here are some wiki sites with a sophisticated look:

splunk>docs
Atlassian developers
PNI
WoWWiki
Any more? If you know of other pretty wiki sites, please add a link in a comment.

What’s in a name?

A couple of times I’ve heard people say that the name “wiki” puts them off. The word sounds trivial, not suited to the powerful tool they’re looking for. It doesn’t reflect the multifunctional tools that wikis have become. Other people say that “wiki” sounds old and dry – very 90s.

Some wikis have changed their description to “collaboration platform” or something similar. MindTouch, for example, is based on DekiWiki. At the moment, the MindTouch website calls its platform the “Social Help Center with Knowledgebase and Help System”. (Note that David Kowalsky does mention MindTouch TCS in his post on The Content Wrangler.) At Atlassian, there are mutterings every now and then about what to call Confluence. Should the word “wiki” appear on the website, we ask ourselves earnestly? The product page title currently says “Content and Social Collaboration Software”.

My 2c? I like the name “wiki”. It’s simple and cute. It retains the history going back to the very first wiki, invented by Ward Cunningham and opened to the world in 1995: WikiWikiWeb, also known as just plain Wiki.

And you know what? “Wiki hugger” sounds so much better than “collaboration platform hugger”!

Honk, beep and wave

So, honk if you’re using a wiki for technical communication. Beep if you’re considering it. Wave if you’re not. I’d love to hear what everyone thinks about the points in this post. And tell me what I’ve missed!

About Sarah

Sarah is a technical writer at Atlassian, makers of Confluence wiki and other software tools. She has 14 years of technical writing experience, the last four of them on a wiki. Sarah’s new book is about developing documentation on a wiki: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s also about technical communicators. And chocolate. The book covers the points mentioned in this blog post, and a lot more. The book is published by XML Press, and is available on Amazon.com and Barnes & Noble. Sarah’s blog is at http://ffeathers.wordpress.com.

Blog Sponsors

What Tools Do Technical Writers Use

Tom Johnson — Mon, 19 Dec 2011 16:33:14 +0000

Students and others trying to break into technical writing are always wondering what tools they should use. The latest tools survey from WritersUA seems helpful in answering this question.

The survey concludes that some of the most popular tools for technical writers are Adobe Acrobat, Camtasia Studio, Adobe Captivate, Dreamweaver, Madcap Flare, Framemaker, Photoshop, Robohelp, Snagit, and Visio.

Of these tools, Flare scores highest as a tool that participants can’t live without. They ranked it as a 5, meaning “very important.” Presumably this is because Flare does an excellent job in single sourcing to other formats, such as print and mobile. It’s an all-in-one solution, so it by definition it’s important or you’re not using the tool correctly.

The WritersUA survey is a little frustrating because these tools aren’t grouped by category. Some are screen capture tools, others are PDF conversion tools, others are image editing tools, others are video recording tools. I use Photoshop and Snagit, but ranking these along with Robohelp and Flare is to compare apples to oranges. Similarly, Camtasia Studio and Captivate are in another category. It would be helpful to sort the tools by category. (Still, it’s nice to see someone doing a tools survey in the first place.)

Of the help authoring tools, it’s interesting to see Flare rank so high. Flare is an excellent help authoring tool, and with a knowledge of CSS you can completely customize the webhelp and print output to look professional. However, its main failure is the lack of collaborative authoring. If you have 15 writers all contributing to the same help project, you have to import the content from other authors. They can use supporting tools such as Madcap Contribute, or Word templates. You can also try hosting Flare on SharePoint and enabling collaboration this way.

But I’m guessing that Flare is popular because most technical writers are solo sailors on their own ship, without the need for collaboration from other writers. In my career, the number of collaborative projects has been very small. I am usually the only writer for the project, which means collaborative authoring is unimportant. I don’t need a central repository installed on a server that numerous authors can access and pull content from. Content is also not reused between projects, since each documentation project covers a different product.

Sarah O’Keefe also has some comments on the WritersUA tools survey. See her post, The passion quotient. She notes that the survey highlights “the tool for which the importance is ranked the highest.” Despite this criteria in evaluation, I am not sure how I would design the tools survey differently.

Blog Sponsors

Book Review: Developing User Assistance for Mobile Apps, by Joe Welinske

Tom Johnson — Tue, 02 Aug 2011 17:18:36 +0000

Joe Welinske’s latest book, Developing User Assistance for Mobile Apps (published June 2011), fills a gap in tech comm literature that is sorely needed. Joe explores strategies and techniques for providing user assistance for mobile devices, and goes in depth with iOS, Android, Windows, and tablets.

Early in the book, he explains:

Hopefully the organizations that employ us will start buying smartphone devices for us to work with just as they provide us with desktop workstations (13).

It would be odd to be an IT employee in a company without being provisioned a computer. Now that mobile is becoming more common, shouldn’t we also be provisioned a mobile device too, if not several?

One of my colleagues just recently purchased his first smartphone. He decided to buy it himself rather than asking our organization to pay for it. Usually only employees with special needs to be reached outside of work times receive smartphones.

But the world has changed. We know that mobile is quickly becoming the most common way for people across the world to access the Internet. It’s much more common to consider and plan mobile development at the same time that you’re building a browser-based application. Mobile is no longer an afterthought. It should be part of our regular workflow, strategy, and deliverables — not just for developers, but for technical writers too.

Given the need to add user assistance deliverables to mobile, where do you start? Almost every mobile device has an emulator or simulator that allows you to explore the functionality from another computer. You also need the right software and setup. For most of us, this is a new world with unfamiliar terrain. How do you connect, how do you test, what software do you need, how do you publish, and how does it all vary by device? Joe covers all of this in depth for the major mobile platforms.

Additionally, he explores techniques for integrating help into mobile apps. Brevity and user testing are guiding principles. But as for a standard, “the look and feel of the UA is as varied as the apps themselves” (19). You can use everything from Dashcode (a mobile help authoring tool), to text built-in to the app, a standalone webpage, or many other solutions.

As for mobile help formats, I was also pleased to read the following advice for mobile documentation:

Many support situations can benefit from a richer level of presentation to the user. Videos and demos can provide a more engaging experience. The audio/visual capabilities of video make it a great choice for showing complex tasks and helping the viewer feel at ease. Demonstrations are useful for presenting an automated tutorial about tasks and procedures (28).

Yes, even on a mobile device, videos and other rich presentations have a place. When you consider the advanced interactions with mobile devices — the gestures, the pinches and squeezes, the flicks and two-finger scroll, the back swipe, etc., you need to see some of these gestures in action to understand.

Undoubtedly, the diversity of mobile devices makes documentation tricky. Joe says the “wildly different UIs that we find in our apps mean that users can’t necessarily carry conventions from one app to another. Unique icons, buttons, and menu structures can create angst for users” (41).

The operating systems and hardware buttons vary from the iPhone, Android, Windows, and tablets. Android itself has many different devices, with different buttons across the bottom. Not only do the operating systems vary, so do the built-in browsers. You need to test your output in all of these devices.

Add to this mix some difficulty in describing finger/touch movements (are these in your style guide?) and how those gesture words might translate, and you have a real challenge. What may have seemed simple suddenly becomes a full-blown documentation challenge.

Joe’s book is an excellent guide to get started in the world of mobile user assistance. The book is brief (142 pages) but thorough enough to get you comfortable in this space.

To learn more or buy the book, see Developing User Assistance for Mobile Apps.

Blog Sponsors

Lots of Conferences Taking Place

Tom Johnson — Fri, 04 Mar 2011 15:26:15 +0000

Ben Minson and me at the last STC Summit

Have you noticed how many good conferences are scheduled lately? I remember a couple of years ago, when Doc Train conferences ended, and some of us thought the STC Summit was approaching its last time — I thought conferences would become extinct. Today there are almost too many conferences. Here are some of the interesting looking conferences taking place within the next couple of months:

SXSW Interactive – March 11-15, Austin, Tex.
WritersUA — March 13-16, Long Beach, Calif.
IA Summit – March 30 – April 3, Denver, Colo.
Confab (Content Strategy) – May 9-11, Minneapolis, Minn.
STC Summit — May 15-18, Sacramento, Calif.
Congility — May 24-26, Gatwick, UK
Web Content 2011 — June 6-7, Chicago, Ill.

Last month the Intelligent Content conference took place. It seems that the number of conferences are growing. The only conference I’m planning to attend during the next three months, however, is the STC Summit. But that’s only due to time and budget. The Content Strategy conference actually looks really appealing.

———

Photo courtesy of STC on Flickr

Blog Sponsors

Review of Alan Porter’s Wiki: Grow Your Own for Fun and Profit

Tom Johnson — Thu, 25 Nov 2010 15:25:40 +0000

Wiki: Grow your Own for Fun and Profit, by Alan Porter

Alan Porter’s Wiki: Grow Your Own for Fun and Profit, published by XML Press in October 2010, provides an excellent introduction to wikis. This is a short, easy-to-read book spanning about 150 pages. Alan has a keen sense of organization and liveliness in his writing. He carries the gardening metaphor throughout the book, ending with five solid case studies and an extended response to common criticisms against wikis.

Sometimes discussions about wikis make it seem as if they’re a new technology. But Alan explains that Ward Cunningham developed the first wiki in 1995 — fifteen years ago! Despite the relative ease with which Alan responds to wiki concerns (about inaccuracies, lack of participation, disorganization, and so on), wikis still haven’t gained traction as the predominant authoring platform.

One has to wonder, given the many advantages of wikis, why they haven’t they taken off as the platform for web and help content? Especially in an age of collaborative authoring, distributed ownership, dynamic editing, and agile development, you’d think wikis would be the most common platform for help authoring in tech comm departments.

And yet, in the 2010 WritersUA Tools Survey, wikis aren’t even included as a tool (see the survey’s list of tools). Almost every other help authoring, graphics, and video, and layout tool is mentioned, but wikis are absent. Either WritersUA accidentally omitted them (this year and every previous year), or they don’t take wikis seriously, or wikis aren’t considered help authoring tools.

My point is that wikis still have a long way to go toward mainstream adoption, despite their decade-and-a-half presence on the web. Alan’s book is a welcome addition to the promotion of wikis and wiki culture.

Although Alan’s audience seems more focused on new wiki users, he does dive into an issue that I struggle with: wiki round tripping. With round tripping, you publish from a source format to a wiki format, allow the wiki to be updated, and then write your updated wiki content back to your source format. For example, with WebWorks, Alan says the original documentation source is in Framemaker, which they publish to a wiki format using ePublisher. If they did round-tripping, after the wiki was updated, they would write the updated wiki content back to Framemaker.

However, WebWorks doesn’t do round tripping. After users make edits to the WebWorks documentation, the WebWorks team manually updates the source Framemaker files with the changed content.

Even if they wanted to do round-tripping, it isn’t easy to achieve technically. And I assume the technical solution isn’t available because apparently there isn’t a business case for it. Alan says,

When I hear people using the phrase ’round-tripping’ they tend to be talking in terms of automating the process. When I have asked people what the business case is for implementing automated round-tripping, very few have an answer beyond “well it would be cool.

Alan notes that with a multilingual wiki, there may be a valid business case. But for most corporate content, round-tripping may pose liability or legal issues, and requires human intervention to evaluate whether the updated wiki content should change the source file. If round tripping is necessary, Alan recommends making the wiki the original source.

This section was most relevant to me for several reasons. First, round-tripping is very much a tech comm topic rather than a general wiki topic. Second, Alan gets into a difficult issue and explores it in depth. And third, there is no easy answer.

In the authoring process for some of my projects, we do keep the wiki as the original source, rather than maintaining a separate source of content. We all collaborate through the wiki, building the documentation as we go. In my opinion, working in Framemaker and then publishing to the wiki (the WebWorks model) undercuts the collaborative nature and power of wikis. If you’re the only one creating the documentation, it might make sense. But in a collaborative authoring model, with a team of internal and external authors, why create documentation in Framemaker first and then publish it to the wiki? How exactly would you share the content? Also, if community momentum picks up, how can you feasibly input the community’s constant updates back into the source files?

However, if you do use a wiki as the original source, you run into a problem: how do you selectively package up the wiki content and output its content into printable formats? How do you personalize the topics based on specific roles?

These latter questions might be related more to the wiki tool rather than wikis in general. Some wikis allow you to bundle the content together as a PDF output, while other platforms require extensions and hacks to achieve this. Access control also varies widely among wikis. Confluence offers different access control levels, while Mediawiki has an everything-open or everything-closed policy.

Alan’s book makes me reflect more about wikis. Will they ever take off? What holds them back? Is it the lack of a universal wiki syntax? Is it because wikis all too often devolve into chaos? Is it because the fundamental idea of volunteer group writing is flawed? I’m not sure. I prefer wikis more than traditional help authoring tools, but wikis still pose many challenges. I’m glad Alan took the time to write a book on wikis. It will help push tech comm authoring models more toward wikis.

For a sample chapter and links to buy Wiki: Grow Your Own for Fun and Profit, see the XML Press site book page. To read Alan Porter’s blog, The Content Pool, go to http://4jsgroup.blogspot.com.

Blog Sponsors

WritersUA – The WritersUA Tools Survey – Tools

Tom Johnson — Fri, 27 Feb 2009 17:32:30 +0000

WritersUA – The WritersUA Tools Survey – Tools.

Blog Sponsors

Top Technical Communication News for January 2009

Tom Johnson — Mon, 12 Jan 2009 05:29:44 +0000

Download MP3 (to download, right-click and select Save Target As)
Length: 12 min.

In this podcast, I cover the top 10 technical communication news items during the past month. This is a different type of podcast than I’ve normally done. The show notes below are excerpts of what I cover, but without any commentary.

1. Techcomm toolbox

One of the most common questions heard on many forums is “What tool do you use for [purpose]?” Answers vary, of course, because everyone has their own favorites and some folks will even answer that the right tool is “the one that best meets your needs”.

Sometimes, many people will answer that you need to look at the different tools, download trial versions, and test. But where is the list of tools to choose from?

It’s here at TechComm Toolbox, your online resource for all applications, services, consultantsm, and trainers related to technical communication.

2. Emergence of STC groups on twitter

More and more STC groups are joining and participating on Twitter: stcaccess, stcchicago, stchouston, stcboston, stcintermtn. Also, Writer River now has a Twitter feed: writerriver.

3. WritersUA Salary survey and tools survey going on

The WritersUA Tools Survey is underway. The survey is designed to provide our community with a guide to the relative popularity and satisfaction of a number of tools. … The Salary Survey provides a look at the various factors that contribute to higher salaries in the software user assistance community.

4. Jing Pro Released

Jing Pro brings you simply the best-in-class experience for quick visual online conversation. Imagine everything you already know and love about Jing, then add:

* HD quality video for the web
* Direct output to YouTube
* No more branding on the end of your videos.

5. I’m a tech writer photo gallery

Technical Writers (aka Technical Authors, Content Wranglers and Documentation Managers) have an unfair image. This project aims to challenge this image, by showing technical writers in a different light. The photos below are of technical communications professionals, doing a variety of activities.If you are involved in technical writing and you’d like to be included, contact us and send us a photo, together with your name and location.

6. STC to record and make available the entire Summit

Beginning this year at the Summit in Atlanta, STC will capture the content (audio and visuals) of almost every session and make it available to attendees at no additional cost. This will increase the value of your experience tenfold. After the conference, STC will sync the audio with the presentations and make them available (by passcode) for attendees on the STC website. This will allow [you] to “attend” all those sessions [you] missed. It will also allow [you] to revisit the ones that [you] did attend and to refresh [your] memory of the fine points made by the speakers. (From Mark Clifford’s January News and Notes)

7. WordPress 2.7 released.

This may be the last time you ever have to manually upgrade WordPress again. We heard how tired you were of doing upgrades for yourself and your friends, so now WordPress includes a built-in upgrade that will automatically notify you of new releases, and when you’re ready it will download them, install them, and upgrade your blog with a single click. [Also, BuddyPress is in beta: "BuddyPress is a set of WordPress MU specific plugins, each plugin adding a distinct new feature. BuddyPress contains all the features you’d expect from WordPress but aims to let members socially interact."]

8. Alltop publishes Tech Writing category

Alltop is an “online magazine rack” of popular topics. We update the stories every hour. Pick a topic by searching, news category, or name, and we’ll deliver it to you 24 x 7. All the topics, all the time.

9. Camtasia 6 released

When recording audio and video at the same time, it’s hard to be perfect. So we’ve made it easier to fix mistakes. Simply decouple the audio and video tracks to edit them independently. And move audio clips between (and along) tracks to line everything up perfectly. Bottom line: fewer retakes and less time spent on editing.

10. Doc to help releases 2009 version, with ribbon-based interface

What’s new: built-in xml based editor, dynamic help control for embedding help in .net applications. xhtml converter, drag and drop linking, and abbility to import project settings.

Blog Sponsors

WritersUA Salary Survey, Tools Survey, and Upcoming Conference

Tom Johnson — Sun, 11 Jan 2009 06:54:34 +0000

WritersUA has their annual salary and tools surveys going on. Their survey results are among the most influential of surveys, so be sure to participate. Click the following links to take the surveys:

Additionally, WritersUA has a conference coming up at the end of March. Although I’ve never been, everyone I’ve met who has attended has praised the conference. As if this all weren’t enough, they also have a WritersUA Linkedin group.

WritersUA Conference

Blog Sponsors

The WritersUA Salary Survey

Tom Johnson — Sat, 10 Jan 2009 04:39:50 +0000

The WritersUA Salary Survey