Ever take a look at some slick wiki technology and think “Wow, that’s really cool…I want one”? I did, and the results (an internal wiki for the documentation department where I work) were…less than stellar. Here’s how you can avoid my mistakes.

I had been working on a continuing education SharePoint site for the department. There was a wiki webpart available in SharePoint, and I became intrigued. What better way to help department members increase their knowledge about the profession than by harnessing our collective brainpower and talents! We could create collaborative summaries of training we’d attended! The intern could create a “new hire” section! We could have a knowledge base! How cool!

Wiki Dos (and Don’ts)

I immediately set up the webpart, learned how to create and edit pages, and provided a training session for my coworkers. I gushed about the endless possibilities, and then sat back and waited for the quality content to roll in. It didn’t.

Where had I gone wrong? Through the power of hindsight—and the research I should have done before I launched the wiki—I’ve come up with a few guidelines to follow next time. Perhaps you’ll find them helpful, as well.

Start with a clear purpose (a.k.a. Avoid the “if you build it, they will come” fallacy)

If you get starry-eyed over a wiki and then try to come up with ways you could use it, adoption is likely to be weak, as was the case in our department. If, however, you have a genuine process inefficiency or lack of resource that a wiki could help solve, you have a much better chance of success.

This phenomenon is best described by Mark Shead. He defines two types of technology users. Members of the first group identify a problem and then seek a technology to resolve it. Members of the second group, on the other hand, start with a cool new technology and then look for a way to incorporate it into their lives. When members of the first group adopt a technology, they are more likely to stick to it. Members of the second group often abandon the technology after a short time.

Prove how the wiki can benefit users

To embrace a wiki, users must first see how it will benefit them. Provide examples of how their real-world work could be moved to a wiki, and show how it could result in more efficient processes.

Ease existing fears about the wiki

People unfamiliar with wikis may fear that a platform in which any person can edit or delete any page will be chaotic. They may feel concern that a wiki could easily devolve into a free-for-all.

In a company wiki, the accountability for contributions and edits is much higher than in a major public wiki like Wikipedia—no one could leave anonymous spam. And while a small company wiki would likely not have the system of checks that Wikipedia employs, most small wiki communities tend to be naturally self-regulating. Chaotic editing and questions of ownership tend to be non-issues.

Provide proper training

If members don’t understand the broad concept of a wiki or the specifics of creating pages and setting up links, they won’t use it. Be sure to train users on what a wiki is (its purpose and what it’s good for) as well as on the wiki tool itself (how to create pages and set up links).

Don’t make it a chore

Don’t force the wiki upon department members. A lack of posts or edits by a particular member does not necessarily mean that the member is not finding value in the wiki.

Nurture your wiki

A wiki needs care and attention. Having an official “administrator” could imply that content is being policed, but you should ensure that someone performs a few maintenance functions:

• Introduction of a loose organization or structure (perhaps in the form of a home page that links to broad categories).
• Periodic checks to ensure that all pages can be found easily through links to a main page.
• Periodic checks to weed out any spam or mean-spirited contributions.
• Acknowledgement of good ideas, sorting of feedback, and implementation of suggestions.

Use metadata

To keep your wiki well-organized and usable, incorporate metadata. Metadata allows users to sort by category to quickly find what they’re looking for. Many wiki programs allow you to require that metadata be selected and allow you to define your own metadata. Other possibilities for metadata include content stages (can indicate whether the page is new, developing, or complete) or audience tags (can indicate whether the page is primarily for management, administration, or developers).

Broadcast updates

A system that notifies members when information has been added or changed will remind users that the wiki exists, and it will help ensure that the content is current, correct, and relevant. Notifications could come in the form of an RSS feed, or they can be as simple as an email alert. Users may prefer to receive a daily or weekly digest of changes, rather than notifications about every single change.

Encourage participation

A good way to encourage participation in the wiki is to enlist the help of a select few. You may select the most well-respected and established veterans of the department, or the enthusiastic early adopters of each new gadget, or the department members most willing to share their opinions. Often these individuals can pave the way for the rest. Recruit them to help get the wiki started; the rest of the group may well be more willing to participate after ground has been broken.

Here’s what the Yahoo Pipes feed looks like at the moment.

Writer River Yahoo Pipes feed

It’s simple compared to other Yahoo Pipes feeds. Basically the pipe takes RSS feeds from as many sources as I add here, sorts the posts by the date published, filters out any duplicate titles, and then merges all the information into one RSS feed. Writer River then displays this RSS feed on its home page. When you subscribe to the Writer River RSS feed (or when you subscribe to Writer River’s email delivery or Twitter updates), you’re also subscribing to this same Yahoo Pipes feed.

I’m convinced that human-assisted aggregation and filtering, with the help of such tools as Yahoo Pipes, is the trend for managing the deluge of information online. Since everyone is an author, publishing on separate sites, RSS is the only way to keep up. And people are publishing like mad, pushing out about a million posts a day.

Post titles are often hit and miss in terms of quality, so some human filtering is necessary. We need people to pick and choose the good content from the poor. People are naturally doing this all the time. I’m just trying to leverage those efforts in an effortless way to pull all of this good information into one running feed. This is what Writer River is all about. It attempts to gather all of this worthwhile content and help you find better information more quickly. If enough people participate, the quality of content flowing through Writer River could easily surpass the quality of any print publication.

Here’s an example. I like UXMatters, but I missed the latest articles published on it because I have hundreds of feeds in my feedreader and I don’t sit there watching feeds all day. However, Alistair Christie saw an interesting UX Matters article by Mike Hughes and posted briefly about it in his What I’m Reading category. I saw it on Writer River because Alistair told me about his What I’m Reading feed, and I added it to the Yahoo Pipe that’s feeding Writer River. I checked out the article tonight and immediately felt it was a valuable post. Without this human filtering and aggregation, I would have missed the post.

Now imagine if not just one or two people submitted similar What I’m Reading or What I’m Bookmarking feeds to Writer River, but dozens, even 100 people. It would be like having 100 researchers scouring the Internet for you, looking for the best posts available.

Here’s a little more math. Let’s say on average, the 100 researchers post one article a day to their What I’m Reading feed — one article a day they feel is worthwhile. In one month, that would be 3,000 articles.

Now of course not everyone has the same interests and tastes as you, so let’s say that only about 10% of these “worthwhile” articles are actually interesting to you. That still means that in one month, you’ll have 300 worthwhile articles to read.

Compare that to static print publications like the Tech Comm Journal, Intercom, the Communicator, or other print publications, which only have about 10 articles per issue, and you begin to see how valuable and powerful human aggregated content can be. This is the rationale behind Writer River. We now need more people to add feeds to it.

The manual method of going to the Writer River site and publishing a link to your post is somewhat archaic. It takes time and is slow. It takes effort. But the RSS feed doesn’t take effort. It only asks that you share your what-I’m-reading RSS feed with the Yahoo Pipe (by sending it to me, so I can add it), and then you don’t ever have to return to the site again. Content will just flow through the feed, however you choose to subscribe to it.

It makes sense to somehow mark or tag or bookmark or post or share or tweet good content that you read, right? You want to hang on to that article somehow so that you can find it later. That’s the nature of reading. But for online content, you need a method for keeping track of it, because the World Wide Web is too deep and wide and slippery to find something again after letting it go.

For those people who don’t have a blog or Delicious account, or Identi.ca or some other way of posting or marking content, I recommend starting one. One of the easiest ways to keep track of your good reads is through a WordPress.com blog, which is free, requires no maintenance, and provides you with an easy-posting bookmarklet that allows you to quickly add a link in two clicks from any page you’re reading.

Let’s pull together these efforts. Rather than having everyone run in their own direction, which accomplishes little, let’s harness all these individual efforts (which people are already doing) and turn them into a massive collective effort that dwarfs anything one simple person can do alone. Send me your category-specific RSS feed or links page and we’ll build an information machine that churns out the best content of the web without requiring you to do much at all to find it.

Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services.

To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral.

The other videos are fairly simple, with short looping background music, professional voice talent, and a read script. The defining quality is that each video is short, some as short as 25 seconds.

The videos aren’t integrated with the text help. So if you don’t feel like watching videos, you can’t easily read the same topic. Google Voice does have help text, but it’s on another page, only linked to from the videos with a tiny, hardly noticeable help link in the footer. It’s almost like one group produced text, another produced help, and they published them independently.

The video windows are small, under 500×500 pixels. The small video window allow you to easily move from one video to the next without losing your place in the site. If you click outside of the window, the window doesn’t automatically minimize, which is nice. You have to close the pop-up window to go back to the list of videos.

All the videos are pulled in from Youtube, so they’re shareable. After one video ends, you see a list of related videos, but the related videos aren’t other Google Voice videos. Instead they are other Google services. So the related videos somewhat fail if you’re trying to learn more about Google Voice.

You can’t comment on the videos, or upload your own, or do anything other than watch them. Unlike the Michael Pick videos on WordPress.tv, Google’s videos are somewhat boring. Except for the overview video, which contains an animated stick figure, they lack a sense of being cool. They feel a bit corporate.

Similar to the length of the videos, the help content is also short and to the point, but the help topics are too text-heavy, with almost no illustrations, diagrams, or screenshots. The pages are embedded on the web, and navigating the topics is somewhat tedious. A search field appears at the top of the help, but if you search for the word “videos,” nothing appears.

Glaringly absent is any printable manual. You can print a single page, but not a group of pages in a PDF manual format. Additionally, Google does not provide any kind of quick reference guide to get started.

You can’t comment below the help topics, but there is a forum. The forum allows you to be notified by email and see the most popular discussions. You can also read a Google Voice blog, but the blog, like the help and the videos, isn’t well integrated with the rest of the help materials. It somewhat lives on its own. Google’s blog also takes the backward position of disallowing comments and only allows linkbacks to the posts.

One interesting characteristic of Google Voice help is a lack of parallelism in the topics. Here’s a list of video topics:

• Call screening – Announce and screen callers
• Listen in – Listen before taking a call
• Block calls – Keep unwanted callers at bay
• SMS – Send, receive, and store SMS
• Place calls – Call US numbers for free
• Taking calls – Answer on any of your phones
• Phone routing – Phones ring based on who calls
• Forwarding phones – Add phones and decide which ring

The help topic titles are similarly unparallel. Usually help contains all verbs or nouns in a more parallel list.

My Analysis

Google puts a lot of effort in the overview video. That’s a smart move. When people want to learn about Google Voice, the overview video communicates the service in a catchy way, with more of Google’s branding. This video is probably watched thousands of times (a lot more than any other video), so it makes sense to go to the effort of including animation.

What I don’t like about Google’s help is the lack of integration between the video and help content. Not every topic deserves a video. Many times I’d rather read the help. And sometimes I’d rather watch a video. Separating the two formats so strongly is a poor usability move. The forum and blog also need to be more closely integrated with the other help materials.

Additionally, the lack of any printed manual makes me think Google has no single sourcing strategy. The help content is probably just written as regular text on each page. I would have appreciated the opportunity to print a quick reference guide or short manual, only because reading on the web is a nonlinear experience, and moving from one topic to another without any logical sequence can be tiring.

I also think Google chose the wrong voice for its videos. Google is playful, young, and irreverent. But the voice they chose is professional, corporate, scripted, and somewhat ordinary.

I’ve been thinking a lot about voice in videos. Professional voice talent is not necessarily engaging. It sounds professional, but a professional voice isn’t always what users want, even if it’s what they expect. Users want a voice that is friendly, engaging, conversational, and real. I wouldn’t even mind it to be a bit spontaneous.

In the past, I’ve recommended that beginning writers create documentation for any open-source project they can find, such as WordPress, Audacity, or projects on SourceForge.net. However, our organization now has about ten open source projects that would provide an ideal opportunity for entry-level writers to gain real experience in technical writing. These projects are located at https://tech.lds.org/wiki.

The open source projects are designed to allow members of the Church of Jesus Christ of Latter-day Saints (aka the Mormons) to participate in some of the technical projects of the Church. However, you don’t need to be Mormon to help out. In fact, not being Mormon may provide a more realistic technical writing experience, as you’ll be working in a world of terms possibly unfamiliar to you.

In contrast to other open source projects, working on the open source projects at the LDS Tech Wiki will allow you to interact with designers, testers, developers, and project managers. You won’t just be writing help documentation for a stagnant application coded long ago. Instead, you’ll be able to create real documentation for a handful of active, interesting projects that you can showcase to employers.

What kind of projects are available? Here’s a page where all the projects are listed. The projects include the following:

• EBuilder Application
• Church Historical Timeline
• Coda
• Bishopric Scheduler
• EBuilder Application
• Home Teaching / Visiting Teaching
• IPhone Scriptures Application
• Local Unit Website Project
• Mormon Channel iPhone Application
• Recreation Properties Application

You can include any help materials you write for these applications in your portfolio. Trust me that a strong portfolio can trump years of experience as a technical writer. I landed my first job as a technical writer because I had a strong portfolio, which didn’t even include any real technical writing projects. Imagine how persuasive your portfolio would be if you actually had several technical writing projects you could highlight and discuss.

If you’re interested in getting involved, complete the requirements for participation. And then contact Tom Welch, the director in charge of these open source projects. (Alternatively, let me know and I’ll point you in the right direction.)

If you’re interested in learning more about the organization managing all of these open source projects, see Mormon.org, listen to audio at Mormon Radio, watch videos on the Mormon Channel on Youtube, or check out the resources at lds.org.

Trees, maps, and theorems, by Jean-luc Duomont

I’m currently reading Trees, maps, and theorems: Effective communication for rational minds, a new book by Jean-luc Doumont. The reason I wanted to read the book is for Jean-luc’s expertise in visual design and page layout, because I thought it could help me design better quick reference guides. Although very little of the book deals with design and is more geared toward engineers (the “rational minds”), he does address page layout and intuitive design in a couple of sections. Here are a few passages of advice:

• “Leave more distance between unrelated items than between related ones.” For example, headings should be close to the text they belong to, rather than equidistant between the last section and the new section. (This principle is termed proximity in Robin William’s Non-Designers Design book.)
• “Be visually consistent: format identical items identically, similar items similarly, different items differently.” This helps the reader understand and predict the relationships between the various information units at a glance.
• “To indicate hierarchy, display more prominently those items that rank higher or that are more important.” Again, in other circles, this would be the principle of contrast.
• “Make sure that each page guides the readers visually along a useful reading sequence or, alternatively, that it gives a clear picture of possible entry points.” This principle is especially important. A document without a clear focal point for readers can lead to a confusing design, such that you look at it and you’re not sure where to begin because you’re eye is drawn everywhere and nowhere (p.73).

Jean-luc’s book has a unique page layout itself. The format is large-print (hence the excessive cost of the book, $99). Each section is usually contained in one bifold spread (by that I mean across two full pages). But you read each spread from right to left. Two columns are on each page. The right column on the right page contains a general explanation of a principle. The left column on the right page contains a minimal graphic. The right column on the left page contains more practical application of the information. And the left column on the left page contains Q&A about the topic. Here are a few sample pages. It’s a weird structure, I have to say. There isn’t much flow from page to page, and I’m not used to reading from right to left. Still, it is consistent.

In “Achieving simplicity and harmony” (p.75), Jean Luc argues that with formatting, writers should use “a healthy dose of self-restraint” instead of indulging in the many layout possibilities that desktop publishing software offers. He recommends black for type color and white space as a principle means of adding contrast. “To make a piece of text stand out,” he says, “just set it apart: increase its distance from other items, thus surrounding it with space.”

Jean-luc also recommends using a single type-face with a couple of type sizes rather than multiple type faces: “Select faces within one family, as these were designed to work well together” (p.74). And he encourages left alignment of the text, with other objects below it aligned along the same left edge. You should only make the decision to justify the text if you prefer a more formal look and if the text blocks “align nicely with the other items on the page” (p.74).

Here I have to pause and make a small comment about a strange, almost OCD quality of the book. Every paragraph of Jean-luc’s book not only has justified text, but the last line of each paragraph ends perfectly justified as well, so that each paragraph is an exact rectangle, but there isn’t much extra spacing between the words at all. At times the content seems to have been written to fill a perfect block form. He doesn’t address this preference of his, but I remember some discussion about it at a presentation he gave at the STC Summit a few years ago.

As for color, he recommends minimalism as well: “Unless you master color design, use few colors, perhaps just one (besides black) in a few tints. Design the page in black and white first, then apply color in touches wherever it adds value” (p. 72). His book’s design illustrates this principle. Drop caps are orange, graphics are grey with a tint of orange, the sidebar is shaded gray, and everything else is regular black, with ample space in the margins.

Finally, he recommends avoiding underlining, bold formatting (within paragraphs), uppercase, and unusual fonts. Overall, Jean Luc is a design minimalist, preferring few colors and fonts and a consistent, simple page design.

As for the question of whether to design the layout before or after writing your content, Jean-luc says, “Logically, a text must have been drafted before it can be formatted, so drafting appears before formatting …. Still, the format might pre-exist or be designed before the text is drafted. Layout constraints, as on the length of texts, should be identified early, so the texts can be optimized accordingly” (p.72). In other words, you write before you apply format and design. However, it’s a good idea to know the constraints of your design before you start writing.

That’s about the extent of the discussion on document design. (He does have a lot to say about the structure and organization of content, such as putting your conclusions first and providing a table of contents, but that wasn’t my primary interest.) Overall, Jean-luc feels that advanced page layout, with multiple colors and font faces and a complex structure, more often than not comes across as amateur and conveys “visual cacophony” rather than an appealing layout. He prefers to minimize the “signal to noise ratio” by adding as little ink to the page as possible to thereby increase the focus on the content.

In buying the book, I failed to realize that I don’t fit the category of “rational minds.” The book should really be titled something like “Structure, diagrams, and reports: writing principles for engineering and science students.” The trees, maps, and theorems part is merely a cute way of saying this, or referring to hierarchy, table of contents, and conclusions. Most of the advice in the book addresses the situation of the engineer, who must write reports, give presentations, include charts and graphics, and create other engineering documents. It is not for people creating help materials, although there is occasional overlap.

Some sections are particularly geared towards engineers. Talking about charts, Jean-luc says “a slope (a ratio of two variations) is more accurate viewed as a direct linear representation of the first derivative” (p.129). Derivatives? Reminds me of calculus classes I took years ago.

Talking about the idea number for lists, he writes, “Four is a square (2²): it is a combination of two binary options. Four is therefore a useful number of answers for rating scales (++/+/-/–), as it embodies a cascade of two binary choices: first, is it rather positive or negative; next, is it a little or a lot” (p.21). Huh? Are we talking about bulleted and numbered lists or quantum mechanics?

Given the engineering audience, one can’t hope for too much style and flair in the prose, but it reads like a college textbook, outlining basic principles in a flat way. It is too focused on “clarity, accuracy, correctness, etc.” (p.79) to make for a fun or engaging read. The start and stop motion of each bifold spread may make it accessible at any entry point, but it also gives you no lure to move from one section to another.

However, if you happen to be teaching a class on writing for engineers and scientists, this book might be just what you need.

Additionally, it’s more beneficial for me to link to others from my idratherbewriting.com site, because it has a higher authority than writerriver.com. Links from higher authority sites are more beneficial in transferring search engine visibility than links from lower authority sites. For example, a link from NYTimes.com will push you to the top of Google results while a link from Sam’s vacation blog probably won’t have much influence.

So here’s what I did to better search engine optimize my site. I created a new section on my site called What I’m Reading. The page shows all the posts I’m reading (which I want to share), with short commentaries or summaries about the content. This way I keep the keywords and links on my site. I’m hoping that this strategy will create more pull back to my own site and will increase the rank of those I link to, more so than links from Writer River.

I didn’t want to limit my reading page to blogs only, because I read books too. So I used Shelfari, an online bookshelf site, to embed a few bookcases of books I’m reading, books I plan to read, and books I’ve read. If you buy a book through one of my Shelfari bookshelves, I will someday get Amazon affiliate revenue. It just made sense to consolidate everything I’m reading on a single page.

Technically, setting up this What I’m Reading page wasn’t that easy to do. The WordPress geeks can read on for the details, because this post is moving from conceptual to technical information. “What I’m Reading” is a category on my site hidden from the main page and RSS feed. I also excluded the posts from appearing in the Next and Previous links at the bottom of the home page (index.php).

I then used a custom category template, naming it category-1246.php, so that when users click the What I’m Reading category (the category ID is 1246), it opens category-1246.php rather than category-php or archives.php, which is the generic template for all categories. With this custom category template, I customized the sidebar, added some intro text at the top and inserted the javascript code from Shelfari to display the bookshelf widgets.

In the custom category template (category-1246.php), I also hid the post title and manipulated the styles a bit. I hid the title tag because I’m using the WordPress Press It bookmarklet to quickly and easily post links from the articles I’m reading while viewing the articles (rather than logging in to my WordPress dashboard to post them). The Press It bookmarklet automatically creates a link to the article I’m reading, so I didn’t want this link to be redundant with the title of the post—hence I removed the title from the category-1246.php template.

However, here’s where it got tricky. Trackbacks are one of my main SEO strategies, because most people are curious to know what you’re writing about them, even more so than what you add in the comments below their posts. A trackback sends a notification to the original blog authors that someone has linked to them. It’s like tapping them on the shoulder and saying hey, this is what I’m writing about you.

The problem is that a trackback’s link opens the single post template (single.php) rather than the category-1246.php template I customized. This leads to a major shortcoming of WordPress: you can customize category.php, but not single.php.

With a little research, I found a script that I could insert into my functions.php file that gives me the same functionality with single.php as category.php, so I then created a custom single-1246.php that matched category-1246.php, and I added a note at the top letting people know a bit about the page, because I didn’t want people thinking I was scraping their feed (according to Feedburner, about 100 people are scraping [stealing and reposting] my RSS feed). My short commentary and summary next to their links also helps avoid the appearance of scraping.

I also created a custom RSS feed and email delivery option for content specifically on my What I’m Reading page. However, I wanted the posts to update my regular Twitter feed (where I have most of my followers). Using Twitterfeed, I pointed the secondary RSS feed to my main Twitter account, so now I have two feeds pointing to my Twitter account. When my main feed updates Twitter, the tweet is prefaced with New Post. When the What I’m Reading feed updates Twitter, it’s prefaced by Recommended Read.

Now, there’s another complication. I’m not abandoning Writer River (a community link blog I started) by any means. I’m trying to move to a model that allows more flexibility and automated submissions. To accommodate this, I had to change Writer River a bit. First, because of all the spam that keeps seeping through, I changed the default registered user role to Contributor (which means I’ll have to approve their drafts first). For people I recognize, I’ll keep their role as Author.

Additionally, the Writer River home page now shows an aggregated RSS feed rather than links to the direct Writer River posts. The aggregated RSS feed displays results from my What I’m Reading category feed, the Writer River feed, and anyone other “good-reads” type feeds that people want to submit to me. The items in the feed are sorted by date.

To aggregate the feeds, I used Yahoo Pipes, which allows you to create and filter and apply rules to large numbers of feeds, and then spits out a single RSS feed from those multiple feeds.

I created a page on Writer River called Latest Posts, and I set this as the home page of the site rather than a reverse chronological list of only the latest posts from Writer River. (You can do this with WordPress through the Settings > Reading options.) On this new Writer River home page, I used the Simplepie plugin for WordPress to parse and display the Yahoo Pipes feed.

The benefit of displaying an aggregated Yahoo Pipes feed on Writer River rather than just content posted to Writer River is that it allows every blogger to do what I’ve done with my What I’m Reading page. Bloggers can simply designate a category that says “Recommended Reads” and select it when they post links to something worth reading.

I guess this assumes the bloggers would also be on WordPress, because WordPress has feeds for each category by default. For example, the feed for my What I’m Reading category is http://idratherbewriting.com/category/whatimreading/feed. I’m not sure if the same is true for Blogger and other platforms.

So if you’re a blogger and you have a category for good-reads, or something similar, let me know what the RSS feed is and I’ll aggregate it with the Writer River Pipes feed.

Finally, to encourage people to share links on Writer River, I created a Spring Widget, which is a little RSS reader that anyone can embed in the sidebar of their blog. To get the code for the Spring Widget, just click the Get this widget link below the Spring Widget.

I want to personally thank Alistair Christie, a tech comm. podcaster and blogger in the UK, for providing feedback and advice on how to handle the Writer River setup. If anyone else has suggestions for me, please let me know.

I am a lot of different things to different people. To some, I’m a blogger and podcaster. To others, I’m an employee and team member. To others, I’m a church member and scout leader. To others, a basketball player. To others, a friend. To my wife, a husband. But to three young girls, I’m a dad.

In the NY Times article, Michael Winerip explains that some years ago, he was putting in 11 hour days with a 2.5 hour daily commute. When he finally arrived home in the evenings, his children would catch just a glimpse of their father before bedtime. Winerip was upset about missing his kids grow up. And his wife felt like her career was suffering due to being off track as a stay-at-home mother. So they switched, and he became the stay-at-home parent to raise their children while she worked.

A while back I wrote about this dilemma in my post Telecommuting into Nonexistent Worlds. If my wife suddenly wanted to work outside the home and could support us, I would trade roles in an instant. But things being as they are, that reversal probably won’t happen anytime soon.

But that doesn’t mean that, as a father, I can’t get more involved in my kids’ lives. Winerip says the great barometer of parental involvement is whether you plan your kids’ birthdays or whether you just help out.

A few weeks ago, I had a memorable conversation with my eight-year-old daughter (Sally on Jane’s blog). Jane was upset with me for having skipped her brother-in-law’s graduation, and for a few days I was in the metaphorical doghouse that all husbands are sometimes placed in.

In the doghouse, I spent a couple of evenings at the park with the kids. One night, I was sitting on a grassy knoll next to Sally watching baseball (the other kids were rolling on the hill), and I started to ask Sally her opinion on a range of dilemmas I was facing, everything from how to get out of the doghouse to whether I should keep doing WordPress consulting to whether I should attend a certain event I didn’t want to attend. I had a lot on my mind that day and decided to do a role reversal: rather than be the parent always giving advice, I asked advice from Sally.

To my surprise, she had solid advice for every question I asked her. It caught me off guard at first. She was really smart. What I thought was complicated, she stripped down to the basic question in a few seconds and told me what to do. The wisdom of a child. The questions weren’t complicated to her; she didn’t deliberate about the dilemmas and weigh pros and cons of each option. They seemed like such simple decisions to her. She even laughed a few times while giving me answers.

In a way I’m grateful for being in the doghouse those evenings, because it changed how I acted as a parent. I still continue to ask Sally for her advice. For example, after I wrote a draft of my Lifelines to the STC post, I felt uneasy about it. The original version was quite a bit more negative. I asked Sally if I should publish it. She asked me if the STC was something I wanted to continue or something I wished would end. If I wanted it to continue, she said I should soften my post. I ended up rethinking some of my points and softening the post, and I’m glad I did. Thank you, Sally!

After this role reversal experience, I feel more respect for my children. They aren’t just little people needing my full attention and parenting; they are smart little people who see the world in clearer, simpler ways than I do. I don’t know if I ever possessed the same uncanny commonsense when I was a child, but if I did, it’s something I would like to regain. Perhaps this is one reward for being a father—having the gift of children to show you what you lost.

Here’s the situation: You’re writing documentation that will be printed in large quantities. At the deadline for printing, the software still has a few bugs. If you mention the bugs in your documentation, it’s likely the printed documentation will still be around after the bugs are fixed, making your documentation out of date. If you don’t mention the bugs, it’s likely that users will be confused until the bugs are fixed.

Do you lie and pretend the bugs don’t exist? Do you boldly write results statements that you know are pure fiction? Or do you describe the bugs in their nitty, gritty, ugly details?

Normally, I would press developers for a timeline as to when the bugs will be fixed, and then compare that timeline against the longevity of the documentation. But projects aren’t always that neat. Answers are often vague. Release fixes are arbitrary. Is the bug truly fixable? No one really knows. Maybe. Probably. When? We’re not exactly sure, but it’s a high priority. It should have already been fixed. Apparently we’re still working out the kinks.

I think project managers are always a bit wary of bug warnings in documentation. It’s hard to describe a bug in a positive way. People don’t like it when you’re negative. You are, after all, the voice of the team. Laying out the truth in all its detail usually breaks the standard tone of most documentation. “The Widget tab has some quirks with it. It only displays correctly in Firefox. Also, one of the fields doesn’t actually send information anywhere. It was deprecated functionality from an earlier version that we decided to leave in because it was a low priority item. Avoid clicking the buttons twice unless you want the system to crash.” You can’t really write that kind of stuff.

When it comes to truth, my approach is to be candid and honest in formats that live on the web, which I can update on the fly. But when I’m printing hundreds of copies of a guide, which I know will be pinned up on walls, filed in desk drawers, and laminated for long-term reference, I often lie and don’t mention the bugs, hoping that developers will soon fix them and convert my fiction into truth.

Almost the exact same argument could be made about the STC and its financial trouble. In case you haven’t heard, the STC’s finances are facing crisis proportions. Unless membership stabilizes, it could go out of business in a couple of years.

Sarah O’Keefe wrote an insightful post about the need for the STC to increase its velocity, community, and openness. Keith Anderson also wrote about the STC issue, pointing out that the problem started long ago, not just with the recession. Both posts got me thinking about the issue tonight.

I agree with Sarah and Keith’s analyses. I don’t necessarily have a solution to the financial problems of the STC. They do seem to be a bit behind the times. For example, two years ago I was excited to learn the website was going to be redesigned. If I remember correctly, it was announced at a conference. But the only difference I can see now is the big blue buttons and the redesigned logo.

News & Notes is still delivered in an email, without the ability to comment. In fact, when the president asks for suggestions to the financial crisis, I would have loved to see an open, blog-like format for discussion. The Twitter hashtag #stcorg was at least a good idea, though.

Intercom, one of the most valued benefits of membership, is still not online in an interactive way. You can’t comment below articles. To see the articles, first you have to log in. After logging in, you see a screen that gives you options to either “manage” or “pay,” and you realize the navigation bar is completely different. After retracing your steps back to the main site and navigating to Intercom, the site template looks different again (which is fine), but when you click Search Articles, you get a blank screen. Fortunately, there is a little search box in the upper-right corner, if you can find it. It’s just a kludgey type of experience.

The live web seminars would be a good service if they were free. I have to admit, I dislike webinars. Registration is cumbersome, the scheduled hour is never convenient, I loathe staring at a Powerpoint on a screen for an hour, the audio is poor, and they cost too much.

I have more than 120 podcasts available for free on my site, touching on practically every topic of interest to technical communicators. The STC seems to have never caught on to the idea of podcasting. Instead, they view the web seminars as a revenue tool rather than a learning tool. If the true purpose were to help educate technical communicators, they would dedicate a podcasting resource to create engaging, regular podcasts similar to the podcasts available from the New York Times (such as Tech Talk, one of my favorites).

I don’t mean to sound like a complainer. I like belonging to an organization, a professional society. In fact, when I made the switch from copywriting to technical writing and discovered the STC for the first time—my local Suncoast chapter—I loved the group. I learned so much from the interactions with my colleagues. It was a solid support network that helped push me further into the industry and see the best direction to go. Without the organization of the STC, I’m fairly certain that close-knit group that gathered regularly would have never existed.

But if the STC were to dissolve, although it would be a tremendous blow to the communities across the globe, the hundreds of tech comm. bloggers would still create engaging content to read. Academics and other authors would still publish books and articles. Vendors would still continue to develop and innovate products. Listservs would continue to flourish. Conferences (though smaller) would still be held. The profession would continue to thrive.

I’ve rambled a bit here. To be a bit more practical, here are a few recommendations to help solve the problems of the STC:

1. Move to more of a virtual office model, with an office in a less expensive area. Rely on more member volunteers to get the work done.
2. Convert Intercom to a blog-like format rather than a print magazine. Same with the Tech Comm Journal.
3. Make the Intercom the centerpiece of the STC site, with a more robust search engine and easy navigation.
4. Hire a professional podcaster (not me) to create several podcasts a week, made available on the site for free.
5. Convert News & Notes into an interactive feature of the STC site.
6. Redesign the STC site using a more interactive, web 2.0 platform. For example, provide more of a social network experience (kind of like the Content Wrangler’s Ning, but better) that appears when you log in to the STC site.
7. Keep recording the annual conference sessions, but make them available online for free to all STC members. To reduce costs, forget the screen recording and instead buy high-end digital recorders and train the conference staff on how to use them.
8. Create sophisticated Yahoo pipes or other mashup filters that aggregate online content written by tech comm. bloggers and other authors around the world.
9. Help members stay updated by holding regular tool training sessions using a service such as Adobe Connect.
10. Create an stc.tv site modeled after wordpress.tv, where chapters can share recordings of their presenters. Provide training on how to record chapter presentations (either audio or video or both).
11. Allow members to join all SIG listservs for free as part of their membership rather than restricting it to just one.
12. Provide a more comprehensive job database, with people actively incorporating jobs from a variety of sites. Allow recruiters to post jobs for free.
13. Provide more guided learning tracks for the different paths people can take in the profession.
14. Rather than ignoring it, leverage Geoff Sauer’s tc.eserver.org–the most visited tech comm resource in the world.
15. Provide resume evaluation services for job seekers.

Overall, I think most of these services should either be free to members or highly reduced (for example, the $79 webinar fee should be more like $5). The idea that information on the web should be available for free is a constant theme that’s hard to fight against. Closing off and restricting access to information, with the assumption that doing so increases member value, seems to run contrary to directions the web is heading.

For example, the New York Times previously tried charging for access to the op-ed columns. Eventually they let go of that model and opened them up for free. The SXSW conference records their sessions and distributes them online for free. Rather than hurt attendance, it seems to increase it. Free is the information economy of the web. Overall, more people would join the STC if they saw the value that it provides. But even when you join the STC, the value you feel isn’t apparent.

Download MP3
Length: 11 min.

Forms that Work

In this podcast, Caroline Jarret talks about her new book, Forms that Work: Designing Web Forms for Usability, which she co-authored with Gerry Gaffney. Forms she discusses go beyond merely the type of IRS forms you fill out at tax time. Every website usually has some online form to collect information from users, from registration information to subscription information to purchasing information.

Caroline talks about the perceived value users must feel in order to part with their precious personal information. She explores why people dislike forms, and how companies can get around these dislikes to increase the usability of their forms, moving beyond appearance and layout and instead focusing more on relationships and conversation.

See the companion website to Forms That Work.

Buy Forms That Work: Designing web forms for usability from Amazon.

Never fear, Visio is here. Visio has tons of great-looking icons. And they’re all vectors, so they resize seamlessly. There’s only one problem: they’re stuck in Visio.

With a little manipulation, however, you can unfree them from Visio and keep them looking sharp for insertion in InDesign. You need a power app (namely, Adobe Illustrator), but that’s it.

To extract images from Visio and insert them into InDesign, here’s what I do:

1. Open Visio and find the icon you want. Search for “secretary” or “design” and you’ll find the standard bald blue man. Select and copy the image.
   

   Copy the image from Visio

2. Open Adobe Illustrator, create a new document, and paste in the Visio icon. You’ll notice that each of the sixteen million layers for the image suddenly appears.
   

   In Illustrator, you can see see the layers

3. Right-click the icon and choose Ungroup.
4. Now here you can make a few adjustments to the icon, mostly removing things or changing colors. On the Illustrator toolbar, the black arrow allows you to move things, and the white arrow allows you to distort or reshape things. The white arrow is handy, for example, if you want to squish in the line that mysteriously extends from the head of the icon.
   

   Modify the image

5. When you’re finished, go to File > Save As and save it as an Adobe Illustrator (.ai) file type.
   

   Save it as an .ai file

6. In Adobe Indesign, go to File > Place and insert the image. You can still resize it and the vector properties of the image are retained, so you won’t see the jagged edges. In other words, Indesign allows you to embed the image as a vector, rather than rasterizing it and having it become pixilated.
   

   Edges still look sharp in InDesign

If it’s absolutely necessary, you can convert it to a GIF, but the edges will look jagged. Open up the file in Photoshop and go to Image > Mode. Make sure RGB color and 8 bit are selected. Now save it as a GIF file or a Photoshop (.psd) file. The edges will be a bit jagged, but as long as you don’t resize it, the edges won’t be too bad.

Cartoon by Ben Minson. For full details about the giveaway, see this post.

Although there will always be a need for people to explain technical material non-technical people, Ellis said, others may be doing it instead, through the formats users prefer. To survive, technical writers may need to morph into content strategists, managing the information in a systematic way rather than merely creating it.

Ellis started by showing a thought-provoking video from Michael Wesch called “A Vision of Students Today.” In the video, students explain why the traditional educational model is outdated and at odds with the way they learn.

Rather than reading textbooks, today students learn through text messages, virtual chats, Facebook updates, interactive media, blogs, wikis, virtual worlds, collaborative efforts, read/write behavior, forums, podcasts, videocasts, and Google searches. The old book-reading, classroom-lecture model of learning has fallen by the wayside. It’s just not how students get the answers they need.

Although students usually aren’t the target audiences of our applications, the same concept applies to software users. The long manual and online help are declining formats few want.

Ellis relayed an observation from Tony Self, a technical communicator who organizes conferences in Australia. Self says if you look at an online help file from 15 years ago, it looks about the same as a help file produced today. This stagnancy of innovation in the technical communication community is frightening.

Whereas Web technology continues to move forward with daily developments—from Web 2.0 to Bing to Google Wave to RFID technology that scans and displays information in real-time wherever you are—technical communicators are doing the equivalent of writing textbooks for people who no longer read them.

Ellis predicts that unless technical communicators make some changes, they’re not going to be around much longer. The role of teaching people how to use technology will be passed on to others delivering it in the formats the audience prefers, expects, and learns from.

But rather than postulating any kind of new media delivery of technology, such as wikifying all your content, or providing instant support through Twitter, or porting everything into Facebook, Ellis recommends that technical communicators solve a different but related problem: managing the diversity of information.

Because information is fragmented and scattered across a dozen different types of media and sources—RSS content, content management system content, training content, engineering content, support center content, user-generated content, web content, marketing content—a need is emerging for someone to manage it all.

Ellis thinks that if writers can evolve to fill more of a content strategy role, in which they manage the fragmented information, they will survive. Rather than being a “technical communicator,” their roles will more likely be content wrangler, information strategist, user-generated content editor, information assets director, and content use analyst.

Ellis said the idea of Content Strategy and the new role technical communicators must play is something he learned in part from Rahel Bailie and her Summit presentation, “The New Face of Documentation.”

My Thoughts

Ellis and Self are right about the lack of innovation among the formats for technical communication deliverables. We need to evolve. The problem is that there’s no compelling replacement for the traditional formats. A lot of good possibilities exist—wikis, blogs, interactive multimedia—but none seems to be the online help / manual killer.

Another problem is that many of the web technologies aren’t available behind the firewall, which is where much of technical communication occurs. PHP and MySQL (required for almost every Web 2.0 blog or wiki technology) are readily available online, but these open source technologies usually aren’t robust enough for large-scale companies who require MS SQL, Oracle, or other technologies. The Web 2.0 technologies available behind the firewall usually just include SharePoint 2007. You usually can’t take advantage of cool web technologies unless you’re actually on the world wide web.

Personally, I have been trending towards quick reference guides (anywhere from 1 to 8 pages) and short video tutorials (2 to 4 minutes) as my core deliverables. I also create an online help as a searchable repository of answers, but I create it with the idea that it will be searched, not necessarily navigated for information. Single sourcing the full online help to a printed manual is just another step, so I don’t omit it, but I don’t promote it much either.

Overall, I’m excited about the new DITA publishing capabilities of Flare 5, because it means you can push the content out to additional formats more easily. You can convert DITA to the Confluence Wiki format, DITA’s XHTML target to WordPress, DITA to InDesign, DITA to web pages, and other formats.

The key to solving the problem of information fragmentation is to get the content into a format that is versatile enough to be pushed to any format. If you can keep the original source in one location and just export to different formats for your audience, letting users choose based on their learning style and preferences, then you could perhaps solve some of the problems Wesch raises in his video. (The exception of course is video and multimedia, which you can’t simply output to.)

As for switching from content creators to content managers, I’m still a bit skeptical about this. Except for public, web-based, multi-author, open-source software models, I just don’t see a lot of users contributing help content to the corporate-grown applications (except for the big ones, such as Microsoft Office). Most companies want their help content to look attractive and be accurate, and few project managers believe users can and will fill that gap if you take away the technical writer.

Cartoon by Ben Minson. For full details about the giveaway, see this post.

Download MP3
Length: 35 min.

This is part II of the Blogging, Podcasting, and Screencasting presentation that I gave to the TransAlpine conference in Vienna in June 2009. For more details about the podcast, see the first write-up. If you haven’t listened to Part 1 yet, listen to that first (unless you prefer to arrive en media res).

Here’s the accompanying PowerPoint.

If you’re wondering why I didn’t just combine the two audio files in the same post, iTunes doesn’t read the second audio file that way. Also, most people’s attention spans tend to time out after an hour.

As always, I love to hear feedback, so if you enjoyed listening to the presentation, drop me a line or leave a comment. Thanks.