At Borders or Barnes & Noble, I often browse the computer books to see the different ways writers approach help material — especially how they approach the same help material.

The other day I wanted a book on CSS, so I pulled four available CSS books off the shelf and began browsing them. Each book looked respectable, but the CSS Cookbook, by Christopher Schmitt, had a unique format that caught my attention and convinced me to buy it.

In the CSS Cookbook, each topic is formatted with Problem and Solution subheadings. Here’s an example: 

I like the problem-solution format. For one, while sitting there trying to choose the right CSS book, the problem-solution format convinced me that the book would deal with my actual problems, not just provide general CSS rules and principles. That feeling — an extremely compelling one — won me over to the help.

Almost invariably, the reason we turn to help is to solve a problem. Some would say every human action is driven by the desire to solve a problem (People don’t go to Home Depot to buy a shovel; they go to to dig a hole, as someone once said). But it’s especially true for help material. Problems are the explicit motivation for why we turn to help. Consequently, help material that arranges itself around problems and solutions isn’t too far-fetched of a format.

At the Trends Panel at the last STC Summit, the panelists even recommended that technical writers become problem solvers. Write less and think more, they said. You don’t write — you solve problems. As you solve problems, your value in the organization increases. They essentially recast our role from writer to problem-solver.

Perhaps it would change the way we wrote documentation if we looked at help as a collection of problems and solutions rather than features and functions. Rather than asking, What can a person do on this page of the application? instead ask, What problems might my user have here?

At the very least, thinking in terms of problems would perhaps get us out of the vocabulary of the application and into the vocabulary of the user. For example, rather than addressing how to “create navigation menus,” we would be writing about building a “curved tab navigation menu that works even when text is resized” (as one problem in the CSS Cookbook is worded). The first is a general help topic; the second is phrased more after the language of users.

Some readers may object and say that we’re already thinking of problems and solutions unconsciously when we write help. In part, sure. But adopting an explicit problem-solution paradigm would make us even more in tune with the actual problems users encounter. Rather than focusing on the general topics, it would help us focus on the scenarios where users will be challenged and confused.

The problem-solution format has its share of difficulties. The main difficulty is that some topics have problems, and others don’t. A problem, in my mind, is one with specific circumstances and variables. A hairy situation. Here’s an example where the problem-solution format feels forced.

 

In this example, the problem is so simple it doesn’t feel like a true “problem.” And the problem merely repeats the title, so it seems redundant. The repetition isn’t needed, but for consistency’s sake, the author carries the problem-solution format into every topic.

Another difficulty is crafting the topic title. At times the title succinctly states the problem; at other times the title strays from the problem. If the title just repeats the problem, the problem seems redundant. If the title is too different from the problem, the title seems poorly chosen.

In these situations, the saving grace is the Discussion section, which I haven’t yet mentioned. After the Problem and Solution sections, the topic usually has a Discussion section that brings up other related points surrounding the problem. When a topic has a discussion that touches on several related issues or considerations, the repetition at the beginning is forgiveable. In that situation, the Problem section merely provides a concrete starting point for a larger discussion.

Overall, the problem-solution format probably works best for more advanced help, where the solutions are more complicated and involve combining several general principles or bending traditional rules. Despite the challenges I mentioned, in looking over the book, the format appeals to me more and more.

Rahul Prabhakar, editor of the TechCraft newsletter, which accompanies the Technical Writers of India listserv, published an interview with me in the latest issue (June 2008).

You can read it here: Techcraft e-Newsletter Volume 38 June 2008. It’s in the “Spotlight” section near the end.

(You can also log into Yahoo and read it here by going to the June 2008 folder, but Rahul gave me permission to post the PDF directly.)

Tech Writers of India (TWI) is one of the most popular listservs in India, with exactly 2,753 members as of this post.

What’s the interview all about? Me, of course. First we discuss my childhood, then my teenage years, I explain all the places I’ve lived …. Just kidding. It’s an interview about how I fell into technical writing, blogging, and other online mischief, like WriterRiver.com and podcasting.

By the way, I met Rahul at the STC Summit in Philadelphia last month. He’s a genuinely nice guy who was excited by the Philadelphia scene.

You can read more about the Technical Writers of India listserv here. If you’re a reader from the TWI listserv who landed on my blog, consider subscribing to my RSS feed (see the Subscription options in the upper-left).

At the end of many topics in Flare’s help, a What’s Next? section appears. For example, in a topic on Creating a Table of Contents, the What’s Next? feature guesses what you’ll want to do next — enable the table of contents in your target. See the following image.

Having used Flare’s help for a while, I really like this What’s Next? feature. For me, it works better than the See Also references, which are more common. (One time I asked a user why he never clicked the See Also link as he was looking for information. He said, “I’ve clicked it before in other help systems and it was never helpful, so I just assumed I’d have the same experience.”)

Not every topic in Flare’s help has a What’s Next? section at the bottom, but I wish every topic did. I’m surprised I don’t see this feature in more help systems. It seems like such a logical way to end a topic.

In some ways, it helps provide transitional glue from one topic to the next. People can land anywhere in your help system, but through the What’s Next? section, you can recommend where they should go next.

If you add a What’s Next? section at the bottom of each topic, it might also provide a better structure for your table of contents layout. In some cases, the What’s Next? topic may help you see how the table of contents should be arranged.

Jefferson McClure added a thought-provoking article link on WriterRiver.com titled “Myths of Technical Writing.” The article is by Bob Doyle and appears on the dita.xml.org wiki site here. In the article, Doyle and other wiki contributors mention 4 myths about technical writing:

1. The GlueText Myth
2. The Stem Sentences Myth
3. The Front-Matter Page-Numbering Myth
4. The Callouts on Graphics Myth

You’ll have to read the original for the details. The debunking of these myths is supposed to help you embrace a structured authoring methodology like DITA. The myths are genuinely insightful, and it got me thinking about myths in a larger sense.

In part, I’m reflecting on myths because I was recently invited to speak to students at a professional writing conference at BYU Idaho in the fall with the topic, “Three Myths About Technical Writers.”

Apparently, many students pursing English degrees assume technical writers have “sold out.” They think technical writing is a “fallback” career. It’s something you can do if you’re starving and don’t have any other options. Oh, the financial naivete and idealism …

I’m not sure what will convince people immersed in Charles Dickens and Edgar Allen Poe and Chaucer and Emily Dickinson, who are writing about deconstructionism and feminism and the intersection of Shakespearian influences on postmodern authors, etc., that technical writing is more than just “press this button here to program your VCR…”

It will be a challenge, but one worth taking. When I was a student at BYU, I held these same biases against technical writing. I acquired the myths from one presentation by a teacher who represented the English faculty on technical writing. In a nutshell, compared to the other English professors, she was the most boring of any I’ve ever met — by a long shot. She talked about formatting phone books. I whispered a silent vow to myself that I would never, never become like her.  While she spoke of layout and design for banal texts, other professors ignited us with literary ideas.

I now have a personal vow to make technical writing look like one of the most appealing careers one could possibly pursue.

In addition to myths about technical writing as a sellout and fallback career, I can think of at least 10 other commonly held myths surrounding the field of technical communication. I offer them below.

1. Technical writers spend most of their time writing.

Totally untrue. Most tech writers spend about 10% of their time writing. The rest of their time they spend learning applications, noting bugs, providing usability feedback, structuring their content, setting up styles for their help files, troubleshooting their tools, strategizing help deliverables, training new users, formatting and laying out their content, updating existing content, meeting with project team members, and occasionally playing ping pong.

2. You can’t get a job in technical writing unless you have technical writing samples; but you won’t have samples until you have a job in technical writing.

Don’t believe this for an instant. You’re surrounded by technology — your iPod, computer, DVD player, microwave, cell phone, BlackBerry, and everything else. Download a trial version of some help authoring tool, or even just open up Microsoft Word. Write instructions for something. Find an open source application with poor instructions and rewrite them. You don’t have to create an entire user manual. Just give your potential employer some evidence of your capability.

3. A technical writer who has years of experience is more knowledgeable than one with fewer years of experience.

This myth is turning into my pet peeve. How many bios have you seen that begin, “Joe has 15 years of experience …” or “Kate has over 20 years of experience as a technical writer….” Experience means nothing unless learning is taking place. I can go to my same job for 15 years, do the exact same tasks, use the exact same tools, never taking any creative risks or moving into new territory, just doing what I’m told, or what I’ve read, for my entire life. The pace of learning can be compressed into a very short time period, or it can drawn out over a life time. The time (years of experience) does not matter as much as the learning that takes place. (See this related post, MySQL CEO Says, “It is dangerous to hire someone with too much experience.”)

4. The tools you know are more important than your industry knowledge.

Many job ads say you have to know RoboHelp, Photoshop, CSS, HTML, Javascript, C Sharp, InDesign, Dreamweaver, DITA, XML, XHTML, and so on. But really, if you have strong domain knowledge about an industry, that knowledge can be a lot more powerful than a specific tool. For example, if you work in the financial industry, a Series 7 license (which allows you to communicate with investors) is a lot more important than RoboHelp. It can take months of study to get your Series 7, and only a few weeks to pick up a tool. (See this related post, Doug Davis on the Job Side of Technical Writing — Location, Industry Experience, and Salary.”)

5. Be careful about having a blog, because all employers google you and will find it.

When I hear this, I cringe. The discussion always comes up among non-bloggers who think blogs are a wart you need to hide. Sure if you have an embarrassing MySpace page where you mix profanity with vulgarity and other shady content, that’s a site you need to obliterate. But a professional blog demonstrating your knowledge of technical communication can be a powerful tool for getting an edge on other job candidates. It can also serve as a tool for professional development and keep you enthusiastic about your career.

6. Technical writing academics are disconnected with the profession and only have a tenuous idea about the actual practice of technical writing.

Many academics started out as technical writers and worked for years doing the same things we did. Are we practitioners so vain that we think the industry is rapidly changing from year to year, so much so that intelligent people who spend years immersed in texts, studies, journals, and experiments have no idea what our jobs involve? Academics may not be totally fluent with the latest tools, but that doesn’t mean they’re disconnected with technical writing practices and challenges. (See this related post, “Reflections on Allison Reynold’s Talk on Job Skills for the Workplace.”)

7. You can’t have voice or style in technical writing. It has to be objective. And the fewer contractions, the better.

All writing has voice. You don’t have to remove all sense of humanity from your writing. A writer who uses contractions, moves toward conversational style, and truly has voice will provide a better experience for the frustrated user who seeks human help rather than cold robotic formalese. The talk that changed me forever was this keynote by Kathy Sierra at SXSW, where she explains the need for human qualities in help material when users, in desperate frustration, finally click the help button. If you want to sound like a robot, eliminate all contractions from your writing. What tone do you think users respond better to?

8. Technical writers aren’t allowed to contact users directly. They should get their information through the product manager, customer support, and marketing.

Here we see yet another wrong idea that will only put up roadblocks for worthwhile help. Joe Sokohl clarified this principle at Doc Train West 2008, calling it the Kobayashi Maru principle (a reference from Star Trek). He says you have to throw aside the idea that you can’t contact users. Without this contact and the information you can gather from users, you’re hopelessly doomed to write instructional material they don’t want.

9. You can single source your material into all the formats your audience needs, if you just learn the right tool or technology.

When you learn to structure your content with DITA, you can magically transform all your content into every format your users need. NOT. The type of instructions you write for a one page quick reference guide varies from the kind of style you need for an iPhone or for a long manual. While I agree that you can single source online help to a software manual, the idea gets taken too far. (See this related post by Gordon McLean, “DITA Is Not the Answer.”)

10. You have to be quite tech-savvy to be a good technical writer.

Actually, when you become so tech savvy that you can’t imagine users not understanding how to disable a popup blocker or not knowing how to do a simple task, when you are stunned at users who double-click when they should single-click, or who single-click when they should double-click, at this point, you lose some ability to write for the lowest common denominator. It’s not such a bad thing if you’re technically challenged. So are most of your users! You’ll be on a level playing field and will probably write a help manual that actually speaks their language. (See this related post, “The Curse of Knowledge — The More You Know, the Worse You Become at Communicating that Knowledge.”)

In a previous post, I mentioned my desire to use SharePoint as a help authoring platform because it provides a Web 2.0 experience that is company-sanctioned. SharePoint not only has blogs, wikis, and RSS feeds, but also integrates with Active Directory, Outlook 2007, and has integrated search across all content.

However, the more I tried to use SharePoint as a help authoring tool, the more problems I ran into. SharePoint doesn’t handle role-based content very well. For example, if you have administrators and regular users, it’s not easy to create two versions of the same help material. SharePoint does have audience targeting, but only if your audience is already tagged with roles in Active Directory (and if active directory is integrated with SharePoint).

Additionally, SharePoint doesn’t single source well. For example, if you have to create several role-based guides, you’re in for a challenge. You can create views in SharePoint where all content shows, and then copy that content into Word. But then you have to reformat much of it, add cross-references, index entries, a table of contents, headers and footers, sub-lists, and other formatting.

Formatting the content in SharePoint itself is also a kluge. SharePoint’s wikis are primitive. They don’t allow comments. And if you add metadata to sort the wiki pages into different views, the metadata (columns) appear to the user.

SharePoint’s blog posts give you a comments field below the post, but it still looks too blog-like. You lose out on the table of contents navigation pane on the left. You can’t quickly navigate through an outline of content. However you try arranging the help topics, it just doesn’t look like help. Users are a bit perplexed and don’t immediately know how to use the system.

Even more important, though, almost no one comments on help topics. As much as I’d like to web-2.0-ize my help, it’s not the same as a personal blog on the web. People at companies simply aren’t inclined to comment on help, so going out of my way to add commenting features below each topic is like adding engravings in sidewalk cracks — sure it may look nice, but no one has a use for it or cares much.

I didn’t renounce SharePoint altogether. I’m still using the web space to organize my content and the blog to communicate information to users. So I’ve made a compromise. First, I customized the SharePoint site to look like a sharp looking website rather than a SharePoint site. The default help URL in my application takes users to a SharePoint landing page, where they can choose their help deliverable — online help, quick reference guide, user manual, or video. All my help content is hosted on SharePoint, so I can publish and update it whenever I need to.

“Blog” is a button at the top of the landing page. On the blog I post release notes, answers to common questions, and other tidbits of information, like the application’s release cycle and upcoming training. I must admit, though, that I don’t have as much to say on my product blog as I originally thought.

Finally, I’m still tracking visitors to the help. Because of the integration with Active Directory, I can see the names and departments of everyone who visits the help. And they can subscribe to RSS feeds and email alerts for the blog. (Now if I can just teach them how to pull RSS feeds into Outlook 2007 … )

I’m not saying SharePoint can’t be used as a help authoring tool, but it’s more suited to knowledge base situations, where you have hundreds of topics and you’re not expected to format them out into any printable guides.

And I’m also not discounting the value of Web 2.0. In some situations, such as promoting an application on the web, more interactive help topics in the form of blogs or wikis might be powerful. But inside the firewall, people often just want to do their jobs.

I returned to Flare for my core help authoring tasks. Let me just say that in doing so, I felt a sigh of relief. Flare provides the feature set for help authoring that I need — conditional tagging, multiple outputs, modifiable skins, hotspots, advanced styles, etc. Despite its quirks, it works.

The way I see it, I’m taking the best of both worlds and combining them.

 

My site was hacked today. Usually when someone says “my site’s been hacked,” the first response is, are you sure you didn’t screw something up yourself? Yes, I’m sure. Someone twittered that my tinyurl was showing a login page. Actually, for me it showed the install page below:

But I hadn’t been upgrading or installing anything. Something was definitely wrong.

I wondered if it was a hacker, so I searched the WordPress forums and found a post indicating a similar experience. Not only did my blog show the install screen rather than content, the wp_options table in the database also needed to be repaired.

I guess I’m used to not freaking out when things are broken. And just last week, I backed up my blog. So I was calm about it. Still, it surprised me that I didn’t start hyperventilating or getting even the least bit stressed. Maybe that’s a spinoff of having become a technical writer. Oh, it’s broken? Let’s see what seems to be the matter ….

Anyway, if you have the same hacked symptoms, here’s how you fix it:

1. Enter your web host’s cPanel, click the MySQL database button, select the database for your blog, and then click the Repair Database button. This should fix the wp_options table and allow your site’s content to reappear, rather than the install screen.
2. Log in to your site, click the Users tab, and delete any new admin users. I had someone in there with the email mdburke@maine.edu.
3. Delete the 30+ new “Hello World” and “About” posts.
4. Change your password to your site and web host to something much stronger.

That’s about it. I’m not sure what the hacker’s point was. I do have the latest version of WordPress (2.5.1).

As a measure of prevention against future attacks, I installed the Ask Apache Password Protect Plugin, which was recommended in this WordPress Codex article on “Hardening WordPress.” Actually, this plugin turned out to be problematic. It locked me out of my admin panel completely. If this happens, just delete the new .htaccess file that appears in your wp-admin folder, and you should be able to log back into your site.

This past week I had the opportunity to get intimate with Microsoft Office SharePoint Server 2007, aka MOSS 2007. If you’re totally unfamiliar with SharePoint, this post will not get you up to speed. But for those embarking on a SharePoint customization challenge, most likely you’re already familiar with SharePoint. Before you start customizing it, be sure to read these ten concepts and gotchas.

Note: When I say “SharePoint,” I’m really referring to MOSS 2007. But SharePoint actually has two components — a free one that’s available on any Windows server, called Windows SharePoint Services. And an additional layer that gives you more functionality, called Microsoft Office SharePoint Server 2007, which isn’t free. When I use the term “SharePoint,” I’m referring to the latter version, the un-free one.

1. A good SharePoint site is one that doesn’t look like a SharePoint site.

SharePoint provides push-button site publishing, so creating a site takes literally 3 seconds. But all the sites look the same. Having an out-of-the-box SharePoint theme, just like everyone else, makes you look like a novice, on par with the completely untechnical depts who can barely operate SharePoint, much less customize it.

Here’s what the default theme looks like.

More importantly, SharePoint has a lot of negative baggage. All those poorly organized, neglected, outdated SharePoint sites immediately come to the user’s mind. Do you want your SharePoint site mixed in with this connotative baggage? No. You want your site to gather respect from your users. A little awe. Not a sigh and an “oh, another pathetic SharePoint site” response.

Customizing your Sharepoint site should definitely be in the plans. But before you run forward, make sure you actually can run. SharePoint has three levels of rights access: server admin, site collection admin, and site admin. If you only have site admin rights, you’re at the mercy of your site collection admin as far as customizations go. If you have site collection rights, you have a lot more customization power. And if you’re a server admin, you can do almost anything (and probably break everyone’s site in the process.)

If you’re only a site admin, stop here. You can’t customize much of anything. Sure SharePoint allows you to pick about a dozen different incredibly ugly themes, but they all shout SharePoint. If you’re a site collection admin or server admin, keep reading. There are additional themes that don’t look anything like a SharePoint site, but they’re hidden away.

To view these alternative, hidden themes, which look nothing like regular SharePoint sites, you have to activate the site publishing features at the site collection level. See the following image.

(You can click any image to see the full size at a crisper resolution.)

After you activate the publishing feature at the site collection level, you can then activate the publishing feature at the site level. Once activated, you have a whole new world of customization features available to you. You’ll also notice that the Site Actions menu has about three times as many options on it.

With the publishing features activated, go to your settings, and under the Look and Feel column, click the Master Page link (this link only appears after you activate the publishing features). Select a new master page, such as Blueband.master, my favorite. See the following image.

Here you can also select inheritance properties for master pages and stylesheets. In other words, you can determine whether the subsites inherit the Blueband.master theme from the parent site. And you can select the CSS file your site uses (choose Band.css).

Note: I’m not sure that the Blueband.master is a “theme,” rather than just a different master file. But it seems like a new theme to me. In contrast, the default “themes” available at the site level, such as Vintage, are really just color variations.

2. Without SharePoint Designer, you can do nothing. With SharePoint Designer, you can do nothing.

If you don’t have SharePoint Designer, you can do very little in customizing your site. That said, SharePoint Designer isn’t very useful. It provides a box of tools in the upper-right, as if you could just insert buttons and controls to pretty up your site. But the toolbox requires advanced knowledge.

SharePoint Designer is only useful in that it gives you access to the stylesheets and allows you to make minor edits to some of the pages. Beyond that, you need to be a SharePoint programmer to actually modify the page. The page’s code is not basic HTML (I think much of it is C sharp, although it is heavily nested in tables).

3. Like the Borg, all content pages render through Default.master or another master file.

SharePoint’s files are all incestuously interconnected. If you’ve seen the Borg, from an episode of Star Trek, it works the same way. The Borg is a collection of individual people that are all controlled through a central person. In SharePoint, that central person is the master file. If you’re using your default theme, it’s the Default.master file. If you’ve selected Blueband, then Blueband.master is your master file.

When you create a page (by going to Site Actions > Create a Page, you’re not creating a page that exists independent of the master. The content page renders through the master, or uses the master to render.

You access the master by going to _catalogs > Masterpage > Blueband.master in SharePoint Designer (at the site collection level). The master has numerous content placeholders, which you see when you open the master in SharePoint Designer. These content placeholders also exist on the content pages that render through the master.

If you delete a content placeholder on the master, it breaks all the pages that use the master to render. So be sure you leave content placeholders alone.

What if you don’t want one of those content placeholders? Well, you can actually delete it. When you open a content page, you’ll see an error message prompting you to find the content placeholder you deleted. Just delete the placeholder from the content page as well and it’ll work.

4. When you edit the master, the core.css file unghosts.

An interesting thing about SharePoint is how it hides the stylesheets. Core.css is the main stylesheet that styles the default.master (and subsequently every other page). But core.css exists at the server level, not the site collection level. It’s only when you start editing the master file that the core.css file “unghosts” and copies down to your site collection level.

To unghost the core.css file, put your cursor somewhere on the master page and change the font through the CSS panel on the left. You might see core.css suddenly appear as a new tab. It is then permanently available in the _styles folder of your site.

Notice I said “might.” Actually, if you’re using Blueband.master, there are at least two main .css files that style the page: core.css and band.css. If you edit the wrong part of the master page, band.css might appear instead of core.css. At any rate, I don’t think band.css unghosts from the server in the same way that core.css does, although to be honest I’m not sure.

At any rate, changing the styles through the core.css file and the band.css file is key to customizing your SharePoint site. Core.css unghosts at the site level, while Band.css is available at the site collection level.

5. You can’t see the image directory that the core.css stylesheet refers to.

As if the confusion over stylesheets wasn’t enough, images are also problematic. First, there are two sets of images: images that belong to the Blueband.master file and images referenced in core.css. The Blueband.master images are available in the site collection level under Style Library > en-us > Images. If you open that folder up in Windows Explorer, you can quickly drag those images to your desktop and start modifying them in Photoshop.

But where are the images referenced by core.css? Remember that the core.css file originally exists on the server and is only copied down to the site collection level after you start modifying your master file. Well, the images don’t come along for the ride. If you want to change an image referenced in the core.css file, you have to download the image from your site (by right-clicking and downloading the image or by noting the file name and path in the core.css stylesheet and then inserting it in your web address so you can view and then download the image).

After you download the image, you can’t upload it to your server image directory unless you have access to the server, and even if you did, it might change that image for all other SharePoint sites on that server.
So you upload the image to a picture library on your site. Then replace the original URL in the core.css stylesheet with the new URL.

Now, you may think that by deleting, overriding, or completely annihilating the images in either Blueband’s image location or uploading new images to replace core.css, you would actually be successful in replacing the previous image. Nope. You have to also check in and publish the image before it appears.

There’s one other problem. Until you publish your images and check in your stylesheets and master file, others can’t see your changes. But the changes appear as if live to you. That’s because SharePoint allows you to work in stealth edit mode. You have to check in all your files and manually publish each image before others can see what you’re seeing.

Here’s the interface where you must publish your images. (Note: If Approve is also an option, do that too.)

Images work the same was a content pages. Content pages don’t appear to others until you publish (and approve) them.

You can shoot yourself in the foot by removing the versioning settings of the document library where your images are stored. If you edit the library’s settings and choose no versioning, then you don’t have an option to publish the images and I believe they never show. I know that I spent a while pulling my hair out before I figured out what was wrong.

6. If you edit the summary view and change the item limit, it breaks the code and you have to generate a new site to figure out the code to fix it.

Do you think I’ve hit on some unintuitive processes for web design? Wait until you read this one. There’s a nasty bug in SharePoint that actually breaks the code if you make a certain modification to a blog site. Open up the category view of a blog, and then edit that category view.

Change the item limit for the default summary view of that category. Bam, it just broke some code. When you click a category now, only one item in the category shows, rather than all posts of that category.
The details aren’t something I want to delve into here. But basically to fix the problem, you have to open the category page in SharePoint Designer and replace some code with the same code from a working site.

Open the category.aspx page in SharePoint Designer. Select the Split view, and then select the Posts web part in the Design view. Then in the Code view, look for listxmlview and replace that entire part with code from a new SharePoint category.aspx page (using the same selection).

I’m not kidding about this. You might not want to make too many modifications to the default category views if you’re using a blog site.

7. If you modify a theme, switch back to the default, and then return to your modified theme, all modifications are gone.

There’s something else you should know about modifying themes. When I first started modifying a theme, I started modifying one of the pre-built themes you can choose without slipping into the Publishing features. I switched to Vintage, modified a bunch of files for an hour or two, and then switched it back to the Default theme because I realized modifying Vintage would take me all day due to the massive number of images and the inability to actually access them in mass.

When I switched back to Vintage, I discovered, in an unpleasant way, that all my changes were gone. It seems that each time you select one of these themes, SharePoint copies down the theme’s files anew from the server, overwriting any changes you made to the theme.

After that, I decided not to switch back and forth between themes, so I can’t say that the same is true for master pages like Blueband. Still, you might want to back up your modifications before switching around those master files/themes.

8. To configure the search to see just blog posts, you have to enter a code that does not exist anywhere on the Internet or help file.

The way I set up my SharePoint site, I chose a blog site and created about a dozen views of the blog posts. Views define specific ways of looking at the same information. For example, one view may include only certain categories, another view may include only the post titles, and so on.

When I searched for a file using SharePoint’s search box, the search results showed all of my view pages first before the actual blog post files. As a result, the search was worthless until the second or third page of results.

Fortunately, SharePoint does allow you to configure the search at the site collection level. You can set a scope with a specific search rule, and then modify the search web part to use that scope. I wanted the scope to return only blog posts, and not any view pages. To do this, you need to enter a certain contentclass code into the scope at the site collection level. This content class does not exist anywhere online that I’ve been able to find. Here it is:

contentclass = STS_ListItem_Posts

The following image shows where you enter that contentclass.

You may also want to restrict the results to a specific folder, such as http://yourdomain.org/blog/lists/posts. Once you set up this scope, the results are much better.

One thing I could never figure out is how to configure the best bets search. Supposedly, SharePoint allows you to enter synonyms for searches and then specify the results. For example, let’s say you use the term “meetings” in your help, but your users also use the term “agenda.” You can create a “best bet” so that when users search for agenda,the search results show URLs you’ve selected. But I was never able to get this feature working.

9. You can’t control the look and feel of the admin side of things.

You may have spent weeks creating a beautiful interface for your users. But there’s one ugly truth that will scare away anyone with collaborative purposes: the admin side of SharePoint can’t be skinned (at least not without some tricky programming).

As long as users aren’t creating posts, or editing wiki pages, or doing anything on the admin side, they won’t know that the admin side still shows the default SharePoint style. But if they do need to go into the admin view, the experience can be jarring, as they go back and forth between themes.

You can’t create a seamless experience with your new SharePoint site. You can only customize the clothes, not the body, so to speak. Here’s what the Blueband master looks like as users view your SharePoint site.

And here’s what the same site looks like when you enter the admin side of it.

Nothing at all like the external interface. By now many of you reading this may be thinking, I’m never touching SharePoint. SharePoint is such a kludge of an application; no way I’m ever using that. Here’s one more little surprise for you.

10. Site metrics don’t tell you what post anyone has viewed.

Admittedly, one appeal of using SharePoint when it’s integrated with active directory is to see, not only the names of your visitors, but the posts they viewed. However, if you’re using a blog site, get ready for some disappointment: you can’t actually see which posts visitors viewed. The metrics entice you with informative looking color graphs, but when you start trying to piece together the information, it’s missing a component, like the actual post name.

This is because I was using a blog site, and the pages I wanted to track were the posts. Surprisingly, posts are actually stored in a database somewhere, unlike wiki pages or other content pages.

The same metrics problem isn’t true if you have a site with a lot of pages. Still, it proved somewhat unclimactic for me. I even attached some hit tracker code onto the post template, but it didn’t propagate to the individual posts.

Conclusion

With all these quirks, it’s hard to see why SharePoint is so popular. I suspect it’s popular because none of these serious flaws are apparent until you try to customize your site, and 99% of the time people leave the sites as is.

Even despite these quirks, if you’re company uses SharePoint, you may be stuck with it. Once you get these concepts down, however, SharePoint is a workable solution as a file repository, a website, and a corporate blog. SharePoint does provide a ton of collaborative features with almost no custom coding. Few other platforms can make the same claim.

Download MP3
Duration: 20 min.

In this podcast, Heidi Hansen takes 15 minutes to discuss five books that she read over the past year and published book reviews for in the Technical Communication journal that STC publishes.

Rather than being an interview-style podcast episode, this audio was recorded by Heidi at her home PC and quickly traverses the five books so that you can learn some key concepts about each book. The following are the five books that Heidi discusses:

• User-Centered Design Stories: Real-World UCD Case Studies by Carol Righi and Janice James, 2007, Morgan Kaufmann Publishers, ISBN 978-0-12-370608-9, 535 pages
• Interaction Design: Beyond Human-Computer Interaction by Helen Sharp, Yvonne Rogers, and Jenny Preece, 2007, 2nd ed. John Wiley, ISBN 978-0470018668, is a textbook at 773 pages $75 softcover
• The Imagination Challenge: Strategic Foresight and Innovation in the Global Economy by Alexander Manu, 2007, Peachpit Press, ISBN 978-0321413659, 272 pages
• Secrets of RSS by Steven Holzner, 2006, Peachpit Press, ISBN 978-0321426222, 344 pages
• Professional XML by Bill Evjen, Kent Sharkey, Thiru Thangarathinam, Michael Kay, Alessandro Vernet, and Sam Ferguson, 2007, Wiley, ISBN 978-0471777779, 856 pages

Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce.

But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help.

(I’m surprised how many people actually tell me that last option, as if in any kind of world that would be feasible.)

The most common responses go somewhat like this:

• I like to jump into the application and then turn to the help material when I get stuck.
• I want to quickly search the help to find an answer to my question.
• I would like the videos sent to me on a DVD please.
• I like to mark up the printed manuals with notes and tabs.
• Videos appeal to people who are visual learners. I prefer to have both video and print.

While it seems like such a simple task — ask the users what they want, and then deliver it — in reality it’s a difficult call. Imagine that you’re planning to feed a large hall of people. In deciding what to feed them, you ask them. But the responses are all over the place: some are vegetarians, some love steak, some prefer barbeque, others want salad, others want pork, others don’t eat pork, others like pizza, others want crab, others are allergic to seafood, and so on. Same goes with help.

However, despite the variety of learning preferences, I think there are several key principles that hold true for almost all of us:

• Long manuals intimidate us and bring out a sense of disgust and depression.
• Short quick reference guides, cards, or other quick material give the impression that the application is easy to learn — therefore we welcome short guides with open arms.
• When we have questions, we prefer to search for the specific answer rather than reading a manual from the beginning.
• When we don’t find the answer within 2 minutes, we give up and ask our neighbor or call someone.
• Seeing a process is often much more useful than reading about it.
• Visual images with callouts and other annotations make instructions easier to absorb while scanning, and our primary reading mode for help materials is to scan.
• If undergoing training, hands-on tasks at a computer lab are infinitely more valuable than a long demonstration at the front of the room.
• Videos are helpful, but if they’re long, or if the user has no control to skip around, fast forward, or go directly to bookmarks, a long video tutorial (more than 5 minutes) is unbearable.

Given this variety of ups and downs, usability principles and learning preferences, what set of help deliverables will most likely appeal to the widest audience? In most situations, one can’t create them all and do a good job. Maybe you’re magically able to single source everything into 7 different deliverables at once and satisfy everyone, but in my experience, that doesn’t really work.

A Telling Moment

My favorite response to the question — “How do you prefer to learn new software applications?” — was when a user pointed me to the Interactive Microsoft Office Guides. These guides were created my Microsoft to help people figure out where all the supposedly intuitive stuff is on the ribbon (I can just see the Microsoft ribbon developers saying, 3 years ago, “Oh users will get it, totally ….”

You might want to take a look at these guides. They’re Flash-based, interactive, and really engaging, not to mention helpful. They show a mock interface of the application. When you make a selection, it gives instruction on how to do the exact same task in Word 2007.

My Analysis

When it comes down to it, here’s what I think most users truly want:

• A comprehensive online source they can search and quickly find answers.
• Short quick reference guides (about 3-5 pages) in an attractive format.
• Short 2-minute video tutorials for the most confusing tasks.
• An ability to interact or contact a real person either virtually or physically.

Notice that I omitted the M word. There isn’t a 200 page print manual in the list. I have mixed feelings about this omission. At the last STC Summit, I attended a panel that discussed whether the printed manual was dead.

Unfortunately there wasn’t a definitive answer. When you omit the printed manual, 67% of the people complain, according to the panel. But apparently if you put the manual in PDF format, in place of a printed manual, the percentage of people who use it is exactly the same. So people don’t use the printed manual, but they complain if you don’t include it.

Creating a long manual is no easy task. To be usable, it needs a meaty index at the back that is thorough, full of synonym references and other user-intuitive phrasings. Additionally, you need cross references throughout. And then there’s a lot of layout and formatting. If you have images that you’re including, the resolutions differ from online and print, so often you need two sets. In many cases (if you’re using a good help authoring tool) you can mostly single source your online help to printed material in one go, but setting up the conditional tags, print styles, variables, cross references, and other considerations in your tool, as well as fixing the inevitable formatting errors, takes a long time.

Rather than labor away at this printed beast, I think I will, for once, skip it and focus on improving other deliverables my users more frequently request.

What help deliverables are you creating for your users and why?

K. writes,

Dear Mr. Tom Johnson,

I am a Post Graduate in English. Recently I am working in a leading public house as writer. How can I become a successful TECHNICAL WRITER?

Please reply me as soon as possible.

K.

Dear K,

The best thing you can do to develop your skills and ability with technical writing is to actually do some technical writing. Find an open source project, such as WordPress.org or Pligg, and write some documentation for it. Most open source projects have poor documentation, so they provide excellent opportunities.

When you finish your user guide or online help, ask someone on a technical writing listserv (like TECHWR-L) to review it. Someone will probably give you excellent feedback. Make a few updates, polish it up, and use it as the technical writing sample in your portfolio. Nothing gets you more familiar with technical writing than actually doing technical writing.

Tom

In Publishing 2.0, Tim O’Reilly says Web 2.0 is “any network effect that makes a system better the more people use it.” Web 2.0 isn’t just user-generated content; it’s harnessing the collective intelligence of your users to make your system better.

O’Reilly’s definition is intriguing because it’s the opposite of the natural law of use. Your car doesn’t get better the more you use it. A music track doesn’t get better if more people listen to it. Your bank account doesn’t improve as more people use it. Your feet don’t get better the more you use them. Very few things actually get better the more you use them. Not Web 2.0. It’s almost paradoxical. The more people who use it, the better it gets.

O’Reilly gives two main examples:

• Google. With Google, every time a user makes a link to another site, Google uses that hyperlink to better inform its search algorithm.
• Amazon. Borders and Barnes & Noble have the same stock of books, but Amazon integrates user reviews and commentary to add more value to their literary collection. With each review, the site gets more valuable.

O’Reilly also mentioned eBay and Craigslist. With each system, the more people use it, the better it gets. O’Reilly also has interesting research on publishing and digital libraries, but I’ll save that for another post.

The question for technical writers is not how you can enable user-generated content with your help, but how you can make your documentation better as more people use it.

I wish I could say I have lots of cool ideas on how to do this. I don’t, maybe you do — refine search results based on user queries, allow users to comment on topics, sort topics based on popularity of views, enable users to contribute their own topics, configure search results based on topic viewing time, provide user community, yada yada yada.

These ideas aren’t new or particularly interesting. Partly it’s because they’re still so pie in the sky, how- -do-you-even-do-it type features. Next I’ll suggest telepathically downloading hotspots in user-brains to note the kinesthetic, verbal, or auditory preferences of your users based on the lobes that light up.

Yet we’re at a point technically where many of these features exist or are available. Our problem is that most help authors aren’t programmers, and few programmers get jazzed about coding help tools. When’s the last time you saw an open source help authoring tool that was specifically designed to create help systems?

(Okay, I did see one last week — called PHP Manual Creator, but it looked really primitive.)

In contrast, look at the explosion of social networks, blog platforms, video sharing tools, and countless other killer web 2.0 apps. Inevitably, help systems will also migrate more towards O’Reilly’s idea of Web 2.0. But rather than seeing these blow-your-mind-web-2.0-type tools emerge from the help developer community (i.e., all those companies who advertise in Intercom), I think the next-generation tools will come from web developers and designers who create them for another purpose. We’ll simply repurpose them to deliver help content.

I’ve been a long-time reader of Digg.com, but just last week it dawned on me that it would be really great if there were a Digg-like site for technical communication. So I decided to create one. It’s called WriterRiver.com and it’s pretty much a Digg clone, except that the entire focus is on articles related to technical communicators.

Check it out by clicking the image below.

How It Works

When you read something interesting online, you can submit the article’s link to WriterRiver.com through the Submit a Story tab. Everything that looks like a post on WriterRiver.com is really just a link to an article online.

When you initially submit an article/story, it appears on the Upcoming Stories tab. As other readers check out the article and vote on it — by clicking the Float link — the vote count for that article increases.

Notice how the word “Floated” appears grayed out in the lower voting button? That’s because I already floated on the article.

When enough people float an article (in this case, when an article receives 5 floats), it automatically moves to the Front Page Stories tab, which is the main page. Conversely, if you dislike the article, you can decrease its votes by clicking Sink. (Float and sink tie in with the river metaphor. On Digg.com, you digg or bury stories.)

Filtering By Popularity

More floats make the article more visible, and fewer votes (or more sinks) make the article harder to find. In the upper-right corner of the site, you can sort the articles by popularity. You can see the most popular articles (the articles with the most votes) today, this week, this month, or this year.

Tip: Set your browser’s home page to show the Upcoming Stories or some other filter. It will help you keep up with the stream of articles.

Other Implications

A few days ago I wrote a post saying I wanted to try a new path. I was mostly referring to my podcast and how tired I was getting of the interview format. The creators of Digg have a companion podcast called Diggnation, in which they discuss the most dugg/voted stories on Digg.com. The format seems to work well — stories submitted to Digg provide endless discussion for the podcast. The Slashdot Review is also a popular podcast based on the top social news sites.

I think that staying updated with the news is one of main reasons people listen to podcasts. I hope to make my Tech Writer Voices podcast more like Diggnation, Slashdot Review, and This Week in Tech. (For this, I’ll need a couple of regular co-hosts, so if you’re interested, email me.)

Pligg: The Tool Behind the Scenes

After looking at the WriterRiver.com site, you might be wondering, Tom, where did you get all the time to create this site? Well, WriterRiver.com is made using Pligg, which is a Digg clone tool. Pligg powers such sites as meaname.com (Spanish version of Digg), Kirtsy (a female-focused Digg clone), and a host of other social news sites. Pligg is easy to install and fairly robust (although it could really use a heftier user manual).

Let Others Know

Like any social news site, WriterRiver’s success depends on how many people use it. In an effort to promote WriterRiver.com, please consider writing a post about it, relaying the announcement on any listserv you’re on, or adding a link to your sidebar. It’s also the kind of site that works well as a home page for your browser (for example, you could set your home page to show the Top Stories today). The more people who submit and vote, the better the content becomes.

The Metaphor Behind “WriterRiver”

Why the name WriterRiver? Dave Winer, the guy who invented RSS, has a metaphor about a “river of news” that I’m partly using. Imagine yourself sitting beside a river watching the driftwood, sticks, fish, brush, eddies, paper cups, toy boats, etc., float by. The river naturally provides a constant stream of new content that moves along in a mesmerizing way. At any time you can reach in and grab something, bring it to the surface (”float it”) so you can inspect it for a while, and then send it back down the river.

Results I’m Hoping for

I hope that WriterRiver.com moves the tech comm. blogosophere and other online formats forward. Through WriterRiver.com we’ll showcase the most engaging articles and posts that 300+ technical writers and bloggers are actively churning out. I have a bucketful of RSS feeds that I scan through each day, and I plan to highlight the good posts in a way that makes them easily findable by others.

I also think the aggregation of the most engaging posts or articles will prove the value of the blogosphere. Certainly the articles posted on WriterRiver.com don’t need to come from blogs, but I’m betting that a good majority will. When others begin to feel the power and addiction of a well-written blog post, it will motivate more writers to start blogs and to follow them. It will also allow new writers to more quickly find reader communities, and it will enable new readers to find engaging writers.

If you have any feedback about the site, I’d love to hear it. Mostly, I’d like to see you submit article links to content you find interesting, and vote on those articles you like.

Thanks for trying this out with me.

On the eve of the highlight conference of the year, I’m out with two colleagues at a grill in Philadelphia, and the waitress is chit-chatting with us more than usual when I mention, in the context of the conversation, that we are all technical writers.

“So you like work for the government? Tell me no,” she says.

And then in a split-second, she walks off, completely uninterested about our profession.

Through this and many other experiences, I have learned that telling someone you’re a technical writer is the best way to end a conversation. My manager Kurt agrees, calling it narcolepsy in a bottle. You say “I’m a technical writer,” and instantly the person listening falls asleep.

This seems a bit of a mystery to me. Is it really that boring of a career?

At night I’m in my hotel bed flipping through the conference proceedings — abstracts of many of the presentations that experts from around the world will be giving. By page 38 (of about 250), after skimming for at least 30 minutes, I’m drowsy with newfound narcolepsy. My eyes become tired and before I know it, I’m gone.

Fast forward four days later, post-STC conference.

If giving the conference a grade, my colleagues and I all agree that it deserves a B-. The tracks had a good variety of topics and speakers, the time slots were well-spaced out, and the conference venue itself had perks — right next to the Reading Terminal Market, in the heart of downtown Philadelphia.

But I didn’t come away with much new learning. I don’t mean to be critical. Perhaps my learning preference isn’t suited to conference style sessions. It’s a hard target — trying to hit the audience’s interests and knowledge level. Time and again I left a session without the high of having learned anything new.

To be fair, you probably get out of the conference what you put into it. And there’s always the value of the social networking that takes place between and after sessions, right? Unless you attend the open jam [karaoke], dance [for married people?], STC annual meeting [snooze], honors banquet [clap clap clap clap clap], and pub crawl [Mormons don't drink], there’s plenty of time to define your own social agenda.

We ended up eating at different downtown restaurants (Marathon Grill, The Continental, Hard Rock Café), walking around the UPenn campus, watching Iron Man, and exploring a bit of Philadelphia. If you don’t arrive with friends, it’s your challenge to make them. The night of the dance, I did venture out into the hotel lobby to see that two technical writers did make special connection.

Having missed Ze Frank’s closing keynote last year, I made a special effort this year to ensure my plane didn’t leave early. Richard Wurman’s talk, however, lacked … the quality of being worthwhile. His strongest message was to ask questions when you don’t understand something, because doing so will “change your life.”

He had a 100 slide Flash-based PowerPoint that he quickly flipped through, allowing us to read the first 10 words of a paragraph on each screen before saying “Next” to the one driving the show. Soon an audience member took over the job of shouting “Next,” and it devolved from there. Kurt ducked out half way through, saying “I’m done.” We found him asleep in the lobby afterwards.

One highlight of the conference was meeting with Ed Rutkowski, Intercom’s editor, to brainstorm ideas for the 2008 calendar. I’m one of six people on a new Intercom advisory panel (submit advice here). I can honestly say that Ed is a sharp guy who is organized and dedicated. The Intercom has been and remains one of STC’s greatest values.

In addition to thematic considerations, my strongest recommendation for Intercom is to add a parallel online format that allows readers to directly interact. The print magazine is good, but I’d prefer to read it online, like a blog, and comment below the article.

Part of this idea depends on the upcoming new STC website, which was supposed to be unveiled at the conference. However, rather than any kind of unveiling, STC leaders merely repeated that they are still working on it.

Another cool part of the conference this year was the #stc2008 tweme. For the first time in STC conference history, a handful of Twitterers tweeted off and on during the conference sessions. On three separate occasions, I twittered about a session I was in, only to find another Twitterer was in the same session twittering his or her reactions too.

Less than 1% of the attendees were on Twitter, but even with small numbers we witnessed the emergence of a powerful, connecting medium. Most of the Twitterers included the tag #stc2008 in their tweets, which allowed each tweet to be aggregated at http://twemes.com/stc2008. I set this as my home page during the conference. The only problem was that the wireless at Philadelphia’s convention center was spotty, only available in about half of the session rooms and for a fee in the hotel.

A few people at the conference asked me if I was interviewing people this year for podcasts. If you remember, last year I interviewed about 20 people. At Doc Train West 2008 I interviewed 10 people (they were longer interviews). This year at STC I didn’t interview anyone.

I had several reasons for not interviewing. First, I was burned out with interviewing from Doc Train. Second, I was presenting in two different sessions — a panel on marketing yourself in a web 2.0 world, and a presentation on podcasting. It’s difficult to present and podcast (and blog and attend sessions and hang out with friends and explore Philadelphia) at the same time.

But more importantly, I’m tired of the interview format. I’ve done too many of them. I’m getting bored with it. I’m not turning from podcasting, but I want to try a new approach. I’m still trying to figure out exactly what that approach is. Maybe a format like Leo Laporte’s TWIT, or DIggnation, or column-style podcasting like David Pogue, or who knows, maybe something entirely new. I know that right now I need a new approach.

I’m also a bit exhausted. During the past two months, I’ve made six different presentations: two to STC chapters (Intermountain and Phoenix), two at Doc Train, and two at the STC Summit. During one conference session interim, I asked Sarah O’Keefe how she maintains the stamina to talk with visitors at her booth all day, make numerous presentations, and live blog the sessions she attends. Her answer: It’s my job.

As Wurman was saying Next, Next, Next to each slide in his closing keynote, and explaining that he was an abrasive old man, I was dying for the conference to end. Well, the conference went on for another day, because our plane arrived late, and so we missed our connecting flight in Dallas. Homeland security confiscated our tiny Benjamin Franklin snow globe at the security gate. And if that wasn’t enough, it turns out when a plane is delayed due to bad weather, the airline doesn’t have to pay for your hotel. Instead, they give you a 20% discount on some two-star remotely located hotel whose shuttle never arrives. This meant my colleagues and I had a lot of time for discussion late at night at Denny’s, during which Ben admitted that his “fun-meter” was broken.

I usually find some worthwhile epiphany after a conference. This time it was unexpected. While I was cutting my steak at Dennys — 1:00 am, tired, out of laughter — I felt that I was indeed moving on to some new online territory. Exactly what I didn’t know. But I knew that I had reached the limit of where I was before, and it was time to walk a new web 2.0 path.

I wrote a guest post at Poewar.com titled “The Intersection of the Personal and Professional, or, Why My Attempts at Nonfiction Essays in Grad School Bombed.” I described one of most significant things I learned at my nonfiction writing program at Columbia (and in life, actually).

I encourage you to check it out, not only because there’s a contest for the guest post that brings in the most traffic, but because I honestly believe it’s the single most important technique writers and bloggers need to implement to engage their audience.

View the post

A strange thing happens when you take an audio file of someone speaking and set it to music — the two separate tracks combine such that the result is greater than the sum of the parts. For example, listen to the 3 minute track below that combines a 1981 speech by Shakespearean English scholar Arthur Henry King with Kiln’s Fyrepond.

I have not altered either track in any way. I simply layered them together. Listening to both the speech and music brought together this way gives more depth to both.

Twemes.com is a service that aggregates tweets that have the same tag. A handful of twitterers at the STC Conference are tagging their tweets with #stc2008. If you go to http://twemes.com/stc2008, you can see a stream of all of these tweets.

Right now the number of people on Twitter at this conference is abysmally low (less than 1%), but through one co-twitterer we were able to lower the AC in a room. It’s a start.

If you’re tweets have anything to do with the conference, just insert the #stc2008 tag in the tweet and Twemes will grab it.

I’m excited about a panel that I’m going to be on with Scott Abel, Rahel Bailie, Chris Hester, and Ann Rockley tomorrow afternoon at the STC Conference in Philadelphia.

The panel is titled “Evangelizing, Proselytizing, and Preaching: Strategies for Marketing Yourself and Your Expertise To Others.” That’s a mouthful. In simpler terms, we’ll be talking about how to market yourself in a web 2.0 world.

At first I didn’t think I had much to say about this topic. After all, it has the M word in there (”marketing”), and the last thing I consider myself is any kind of marketer (disgusting) doing any kind of marketing (repulsive). But when I changed the terms a bit to “influencer” (while talking to Chris tonight), it made everything come into focus. And I suddenly realized that I’m the perfect person for this panel.

Since only a small selection of my readers can actually attend the panel (and because recording STC sessions is prohibited), I’ve posted my panel notes below.

1) How can an employee at a company that wants to move to XML structured authoring become the domain expert in the company? What marketing tactics might they use to position themselves as the expert in the field?

First, as I indicated earlier, I dislike the term marketing. I don’t think of myself as a “marketer” or as someone who is engaged in marketing. I prefer to think of myself as an influencer.

But how can you transform yourself from the lowly technical writer who sits in a cube all day to a domain expert? Or into key influencer on the project team?

First, you need to get a foot in the door. Let your project team know that, for the user documentation, you need to be kept in the loop of anything related to application functionality or the user interface. Make sure you insert yourself into the right meetings and get on the right email loops — under the guise of staying updated.

But instead of just absorbing information in these meetings or email threads, speak up and demonstrate your domain expertise by offering suggestions, analysis, and other insights into the problems the team is trying to solve. If you’re really a domain expert, it will show.

If you have access to a corporate blog (for example, a SharePoint blog or other space), use that and promote it as much as you can in your company. Share your domain knowledge through this publishing space. The more information you share, the more others will see you as the go-to person for information on this topic.

But even if you don’t have aspirations to become a domain expert, you can still transform from tech writer to key project influencer by becoming a user expert. Your largest leverage point is your knowledge of users. The more you know about your users — their complaints, the features they want, the feedback they’re giving, their profiles and habits — the more influence you have on product design. User knowledge transforms you into a key influencer on the product team.

Without this knowledge of your users, you’re only an absorber of information. But if you’re dripping with user knowledge, it can make you one of the most valuable players on the team. Many of the priorities that developers work on for the products I document are priorities based on the user feedback I’ve given them (much of which I gathered while giving training and interacting with users). The project team often turns to me and asks what the users want or what they’re saying about such and such feature. I love that focus.

2) What can an employee of a company do outside of their company firewall to promote themselves as an expert — and why would this matter to others with whom they work?

Outside of a company, you have access to a TON of web 2.0 tools — blogs, twitter, video, Flickr, Second Life, and more. But before you jump into these tools, you have to think about your purposes and the audience you’re trying to win over.

Your web 2.0 endeavors won’t do much good if they don’t reach your audience. Is your audience other technical writers? Great. Is it companies looking to hire contract technical writers? Fine. If you’re trying to market yourself, your content needs to attract that audience.

Once you establish the audience and the content that appeals to them, you need to pump out valuable information in a prolific way. For example, you don’t increase your visibility by blogging once a week or even twice a week. If you’re planning to really crank up your visibility and promote yourself as an expert, blog as much as you can (e.g., daily) about the topic you want to promote yourself as an expert in.

Blogging prolifically comes naturally if you’re 100% engaged in what you’re passionate about. If you’re trying to promote yourself as an expert in XML, immerse yourself in journal articles, books, other blogs, podcasts, email lists, and any other content on XML. Write about what you’re reading. Reflect, analyze, and apply your knowledge.

You’ll have plenty to blog about, and the more you blog about the topic, the more you’ll teach Google to find you in search results. Those searching for information on that topic will naturally be drawn to you, recognizing you as an expert and potentially hiring you. You will saturate Google.

One key technique to increasing your visibility is to search-engine-optimize your posts. People find you through keyword searches in Google. I didn’t really believe this until I started watching my readers via Woopra. 65% of my visitors find me through Google. Those posts I’ve purposely optimized rise to the top. Stack your keywords at the beginning of your title and at the beginning of the first paragraph. Think like a searcher and the keywords will naturally come to you.

3) What things can a technical communicator do who wants to prepare themselves to leave their employer and become a consultant or self-employed?

If you want to leave your employer and become self-employed, I think you have to do more than simply blog. You have to do something that catches the attention of your audience in a major way. One web design company does this extremely well: Headscape. Paul Boag and his colleague Marcus Lillington have a popular podcast called Boagworld.com that has thousands of listeners. It’s a marketing vehicle that promotes their company (Headscape) by branding them as experts and attracting new clients.

Even my little podcast, Tech Writer Voices, has made a sizable impact on the technical writing community for me. It has allowed me to make connections with hundreds of people. Each week about a 700 people download podcasts I’ve recorded. In May I had 4,000 downloads. That’s a lot of reach, and it’s a reach that’s more personal and powerful than merely writing a blog. Wherever I go at this conference — each hall, room, or back alley — I run into someone I know through either my blog, podcast, or Twitter.

Still, despite the effectiveness of my podcast, if I wanted to increase my reach, I could make it a lot more informative. I could make it entertaining, like This American Life. Ira Glass interweaves interviews with an in-depth exploration of a theme.

I could prepare all the content myself and relay it like Jason Van Orden does with the Podcasting Underground. His podcast on podcasting helped him promote himself as the go-to guy for podcasting. He wrote a book, created a course, and provided other peripherals.

Or I could focus the podcast on a topic that there’s not too much info about (e.g., DITA, or breaking into technical writing). I could provide insights, tips, and tricks on this topic on a weekly basis, and then promote peripherals through the podcast — a book, course, CDS, and consulting services.

Another approach to increase your reach is to do a roundtable similar to Leo Laporte’s This Week in Tech, which presents and discusses the latest tech news. This roundtable format works exceptionally well. About four guys go on Skype and discuss the latest tech news. If you have some disagreement, it makes for a really engaging, entertaining show. If you were to create the same show on a topic you’re trying to promote yourself as an expert in, it would brand you as an expert.

Conclusion

Any time you provide a lot of valuable information, you’re going to attract an audience. And you can sell that audience something. The cool thing about blogs, podcasts, and other Web 2.0 marketing vehicles is that it isn’t conscious marketing. You’re unconsciously marketing yourself, building networks, and increasing your potential client reach — all without really thinking you’re doing any of it.

Download MP3
Duration: 20 min.

In this podcast, rich media specialist Todd O’Neill explains how to add video to your training and documentation deliverables. Many technical writers are intimidated by the learning curve, equipment costs, and software they think they need to create video, but actually you can create engaging videos with minimal equipment (e.g., $150 for a Flip video camera) and using software you probably already have (e.g, Windows Movie Maker or iMovie).

In this podcast, Todd lays out the basics for those who know nothing about video. He explains the equipment you need, techniques for minimizing editing time, ways to publish the video online, filming techniques to focus on, and creative ways to package your video for your users.

For more information, see Todd O’Neill’s blog at http://doingmedia.net.

Note: I recorded this podcast at Doc Train 2008 in Vancouver, Canada.

Download MP3
Duration: 10 min.

With all the buzz about web 2.0 deliverables, it’s easy to get caught up in the frenzy and think we need to quickly create blogs, wikis, social networks, podcasts, videos, and other new media for our users. Actually, we have to step back and analyze our users and their needs before creating any help deliverables at all.

In this podcast, Nicky Bleiel says we should talk to as many users as we can — conducting on-site visits, sending surveys, gathering information from Marketing, Support, and other departments — so we can have a better understanding of our users’ needs and the formats and mediums that will work best for them. After completing this audience and needs analysis, we can then go out and create the deliverables that will best serve our users.

She also recommends the book Groundswell, by Charlene Li and Josh Burnoff, to get a better understanding of how to measure web 2.0 success.

Nicky Bleiel is an STC director at large and works for ComponentOne, which makes the Doc-to-Help authoring software. For more information on Nicky Bleiel, see her bio page and visit her new blog.

Note: I recorded this podcast at Doc Train West 2008 in Vancouver, Canada.

If you’re going to the STC Summit in Philadelphia, check out my presentation on podcasting.

The Art of the Podcast

Room: 111AB
Format: Demonstration
Skill Level: All
Time: Tuesday, 4:30 -5:30 pm

Learn how to capture audio from presentations, in-person interviews, phone conversations, and tutorials and deliver them as professional productions that can build relationships with listeners and strengthen their knowledge.

I have a PowerPoint for this presentation here. Even if you’re not into podcasting, but you still read my blog, come up and introduce yourself to me at the conference.

I’m also going to be on a panel about marketing yourself in a web 2.0 world. The title is as follows:

Evangelizing, Proselytizing, and Preaching: Strategies for Marketing Yourself and Your Expertise To Others

Room: 108A
Format: Presentation
Skill Level: All
Monday: 5-6 p.m.

This session will explore ways entrepreneurs and captive employees can market themselves externally (to the greater world) and internally (to their organization) to position themselves as the “go-to” folks for domain knowledge in their niche.

Scott P. Abel, The Content Wrangler
Tom H. Johnson, EMC
Ann Rockley, The Rockley Group Inc.
Chris Hester
Rahel Bailie, Intentional Design Inc.

Both of these sessions are going to be well worth your time (and mine).