Focus on Communication Skills not just Tools

I just finished reading Geoffrey Hart's article, "We're Communicators, Not Just Tool Users," in the current issue of Intercom (STC membership required for online access).

This article actually had me breathing a sigh of relief. I, like many others out there, am in the field that I am because I have an aptitude for communication - whether technical writing, marketing communications, or training. That's not to say I've mastered it all -- far from it -- but along the way, I have learned from others and learned by doing. I do not have a formal education in writing or communication (although I'm currently working on my Masters in Technical & Professional Communication). So, I've always been a little self-conscious about how my skills measure up -- not just in writing -- but also in my experience in using many of the tools out there that technical writers use. Mr. Hart's point is that communication is the skill at the heart of what we do, not the tool we use to communicate. By overemphasizing the array of tools we use, and essentially allowing them to define our skill-set, we do a disservice to ourselves and others. Hiring managers are often mistakenly focused on requiring a certain number of years using certain tools as a means to measure your skills as a writer. That doesn't make a whole lot of sense.

Mr. Hart reminds us that the 80-20 rule applies here. To do 80 percent of our job, writers use about 20 percent of the features of the applications they use. Most of our assignments don't require that we know every bell and whistle of the applications we use, just what is needed to effectively accomplish the job. Many of the software "experts" who do know all the bells and whistles don't necessarily know how to communicate.

My resume contains a list of software applications and systems I've had experience with. I've often wondered what expectation this is setting with potential employers. Do they think that by listing it here, I'm an expert? Is it dishonest to list applications I haven't used in 3-4 years? Should I qualify each item with my skill level? After reading Mr. Hart's article, I'm not as concerned. He notes that many of us do not have formal training on the software applications that we use, but rather, we have the ability to effectively learn software in a few days time without training. Even if we do have 3 years of experience with an application, it doesn’t mean we know all the bells and whistles either. I think he's right about this too. I have had very little formal training on any of the applications I use, and I probably have more practical expertise and know-how than many who sat in a classroom to learn them.

I appreciate Mr. Hart's take on things. I think he's right on many points. It's important to know the tools used in our industry, but people hire us (or should hire us) because of our skills as communicators. If we have the ability to learn new applications fairly efficiently, which most of us do, we should be attractive candidates.

I hope he's right.

Updating Documentation Efficiently

Is there anyone out there that manages documentation updates efficiently??

This is a question I've asked myself and every search engine on the planet lately. So, let me explain a little bit about our conundrum. I feel it a bit premature to even be posting this, as it would be nice to have a solution worked out, but perhaps this will solicit a few suggestions from other readers.

Typically, our documents are meant to be printed and are formatted as such. Although I'm the only tech writer at my company, I work with a group of computer trainers, who also write documentation for end-users. We all generally work in MS Word and when files are published to our internal portal, we PDF them. So, essentially, we've got two copies of every file - one in Word, which is stored in our Document Management System (DMS), and one in PDF, which is on a server that feeds the portal interface for people to find help documentation. The tech documentation is in two places too - in Word format and stored in the DMS and also in a "tech knowledge database" that we've been using for years to keep technical knowledge and documentation in a shared space for all. You might be wondering why the DMS isn't considered a shared space -- it is, but it's a painstakingly slow process for people in other states and countries to access the documents in our document library here. We don't currently have a Content Management System in place....it's in the works, and has been for about 2 years. So, let's just say I'm not waiting for the CMS to be implemented to come up with a way to manage all of this stuff.

Well, as you can imagine, things have gotten a little out of hand. When you look at the latest updated document in Word, it doesn't match the latest PDF that was posted to the portal. Problem is, not everything we write in Word gets posted to the portal, so people "forget" to update what goes on the Portal. We've also introduced a wiki and some groups use that instead of the tech knowledge database. Some people prefer one over the other.

So, we need to come up with a system - to be more proactive in making updates. Best I can think of is that we have to make it mandatory to catalog every user-facing document we produce so that if we make a change it gets posted appropriately. The other issue that might be addressed by this is to alert us when the change we're making to one document should be made to other documents. For example, if something in the process itself changes (e.g., new server names or locations), we make that change to EVERY document that includes that information, not just the one we remembered to update. Seems like all of this should be automated, but aside from just creating a database of sorts with decent views and search capability, I'm at a loss. All of the solutions I come up with seem like we're creating much more work than should be necessary.

We'll be having discussions in our group over the next few weeks to get this moving, and I'll be sure to post updates.

In the meantime....any ideas out there you'd like to share would be most welcome.

Reflections of a Blogger

So, back when I first started this endeavor back in January, I wrote that my blog's mission would be:

...about ideas and observations for technical communicators. Technical communications encompasses so many areas, and I expect this blog will too. The goal is learning. I learn through thinking about things, trying things out and talking with other people. I hope this blog will reflect that environment and that we can learn from each other.

Well, I feel that I've learned a bit - about blogging and the subjects I have written about. Whether anyone else learned anything from my blog remains to be seen. I just added a visit counter to my blog yesterday, so maybe I'll at least see if anyone is coming to the site....I also think I have to adjust the code, as it doesn't seem to only be tracking unique visitors...just my visits, and it keeps counting them every time...

But, blogging is not necessarily an exchange of ideas where we can "learn from each other" -- unless you've found a way to gain popularity and larger readership. That's something I haven't yet mastered -- getting my blog to be "found" through keywords, listings and the like.

But, for now, I like writing about my opinions on subject matters I appreciate. I've contributed to message boards online before, but never had my own blog. I like the writing style that accompanies a blog - a little more casual than other writing projects. On my blog, I write like I speak to some degree, and I like that.

So, I'll continue on and blog away and see what becomes of it. I'm sure over time, I'll learn a bit more about blogging and getting the word out. For now, my "corner" isn't such a bad place to be.

Please keep the user in mind....Please.....

I've been working at the same company for almost 10 years now - in different capacities, but always in the role of determining how we will communicate with our users. Over the years, I've gotten teams to be better and better about bringing training and writing staff into the development cycle early on. There's nothing worse than coming into a project at the end and being asked to write training material or help systems on a product that couldn't be less user-friendly if you tried. It's too late most times for changes to the system and the trainer/writer is left feeling like they're setting the user up for failure.

Unfortunately, every once and a while, we still get thrown in at the end, as is the case with a project I've recently been assigned. The web-based application that I've been asked to write a help system for is one we got from an outside vendor. I can tell we got this one because it was the cheapest one we could find. This application is supposed to track information about the deals we do (I work for a law firm).

So, I met with the project manager last week to go over what was needed and I found that I had to stop asking questions about why certain things work the way they do because I was entirely frustrated with the answers. It went something like this:
Me: Why do we have some fields that are picklists and some fields that are lookups and some fields that are free form, all on the same screen?
Him: Because the information from this field comes from the authentication file and this one comes from the core database.
Me: Why should a user have to care about that or know about that? Can't we just have them enter information in one way?
Him: No, it doesn't work that way. We tried to get the vendor to change some things, but they won't.
Me: OK, I'll figure the rest of the application out myself - you can go now.

Yes, the user can figure out how to fill out each field, but they shouldn't have to. A designer should have usability in the forefront when designing applications. I realize my involvement earlier on in this particular project wouldn't have helped as we have a vendor who has already sold us a product that they know they don't have to fix....we've already paid, after all....

But, if your designers aren't very good at usability, do your user base a favor and have a few people test it out and give you feedback. It can make a world of difference.

A couple of useful usability links
http://www.usability.gov/
http://www.useit.com/

Online Collaboration Writing Projects

I had a chance to try Writeboard, a web-based collaborative writing tool recently. Writeboard allows a group of users to contribute writing and edits collectively, creating new versions and comparing the changes. The file can be exported as a txt or html file for further editing and formatting as well. There are some pros and cons to this tool, which I'll discuss a little later in this blog entry.

Being a "lone writer," I haven't had much of a reason to collaborate on the documentation I write. Instead, I write - other people edit - and I rewrite. However, I, and I suspect many of you, have used collaboration tools that are built-in or are add-ins to Word Processing software. For example, I have used the Track Changes feature in Microsoft Word, which marks changes and tracks which users made which changes. You can then accept or reject the changes for the final version. I've also used Deltaview, a third party add-in for Word that allows you to "run" a comparison on two different versions of documents, resulting in a third document that contains all of the markups. Where I work, we also use a Document Management System called "DOCS Open" which allows us to save different versions easily when making changes. (We're using an older version of DOCS Open.) There are other tools we've created here that enable the lawyers at our firm to collaborate on documents with their clients, but as a writer for IT systems and procedures, I haven't had a need to use them.

Who is Online Collaboration Writing Good For?

• Student groups working on a class project (particularly when not physically located on a campus)
• Writers and Designers who may only be working on the parts of a document that are in their area of expertise.
• Writers in companies that don't have shared network drives where documents can be shared.
• A group of people who have different skills - for example, writer, editor, designer, etc. Each person has a role on a project based on their expertise and strengths.

I used Writeboard and found it easy to use; a little "clunky," but simple. After having worked with more sophisticated tools like Track Changes (I actually never thought of it as sophisticated until now), it seemed too limited to be of much use when other tools are available. 37Signals, the company that makes Writeboard, makes it no-frills on purpose. They don't include the things they don't deem important; only those things that are necessary. They allow the use of certain formatting marks, like bold and italic by using * around the words you want to bold, for example. But, it didn't work for me. I had two headings with body text separating them and instead of bolding the headings with my ** surrounding the words, it made the body text in between them bold.

When working with other writers in the same company, I think it's better to use in-house systems to collaborate. But, if you don't have anything else, then this little free tool could be a useful way to get the text down pat among contributing parties. I'm not the type of writer who just puts text in first and then formats; I start out using one of my templates that contains all the styles I need, so I just organize as I go along.

If you do online writing collaboration (regardless of the tool you use), it's important to have people assigned as "overseers" on the project. For example, one person should make sure the information is technically correct. Another person should make sure that all components sound like they have the same "voice" and style. It's a good idea to agree on styles (for formatting and writing) ahead of the project to avoid headaches later.

Another form of online collaboration is a wiki. We have wiki in our IT department where I work, in which people contribute information on processes for deployment, upgrades, troubleshooting, etc. It works well, as people have been participating and updating as needed. They are not writing formal documentation, but they are documenting procedures and referring to them across IT units. Collaboration in this format works well, as long as people participate. Sometimes, this is the only documentation they need; it's not necessary for me to put together anything formal.

I'm sure I'll do more online collaboration in the future, particularly in the form of wikis. Writeboard and other tools like it, still offer a simple way to collaborate on the text across a disparate group of people, but it just may not be my first choice.

Writing for the Web

I haven't had much experience writing for the web in an official capacity (not counting this blog, of course). But, I wondered what is different about writing for web v. print. Well, quite a few things, but I'll focus here on how web writers may address an audience's needs through their style of writing for the web.

First of all, who is your audience and why are they reading what you have written?

One stark difference in writing for the web v. print is that you have to consider how people will find your content to begin with. Writers for the web should be considering the use of relevant keywords that are used in web crawlers to index your content so people can find it. It's recommended that writers repeat these keywords 2-3 times to give it the right strength for a search. This can be a challenge - you don't want to make is sound like you're just throwing keywords all over the place - you lose credibility. Web writer should also be keeping the tone of the writing (for general audiences) conversational, rather than formal. If your audience is more technical, however, and you expect they are reading your content to be able to DO something, you need to be specific and write to their level. Often the product you are writing about will help determine who your audience is.

However, one major advantage of writing for the web is the ability to format your content in a way that doesn't overwhelm the readers and can address multiple audience's needs all at once. If you had a website for a product that could potentially have different audiences with different purposes, you could format your content in a way that allows the reader to determine which link to click on the home page to lead him or her to the content specific to their purpose -- it's a far cry from handing someone a 500-page manual and telling them to just use the index to find what they need. Keep in mind that some of your readers may need to accomplish different tasks, including: assessing information, learning about something, learning to do something, or need to do something directly as a result of reading your content. The last task is often true for content that is more technical or instructional in nature.

Take for example, a pharmaceutical website like Pfizer's. There could be a wide range of audiences going to their website -- consumers, health care professionals, investors, to name a few. Pfizer addresses this by titling certain sections with "For Health care Professionals" and "For Investors" -- the use of heading help the user know where to go for his or her particular need. They try to address different people's needs through formatting, layout and using links appropriately to assist their readers in getting to the information they need.

Layout is important, not only for usability, but also because people tend to read web pages in the F-Shaped Pattern. According to Jakob Nielsen, "Eye tracking visualizations show that users often read Web pages in an F-shaped pattern: two horizontal stripes followed by a vertical stripe." He goes on to say:

• Users won't read your text thoroughly in a word-by-word manner. Exhaustive reading is rare, especially when prospective customers are conducting their initial research to compile a shortlist of vendors. Yes, some people will read more, but most won't.
• The first two paragraphs must state the most important information. There's some hope that users will actually read this material, though they'll probably read more of the first paragraph than the second.
• Start subheads, paragraphs, and bullet points with information-carrying words that users will notice when scanning down the left side of your content in the final stem of their F-behavior. They'll read the third word on a line much less often than the first two words.

Unless people are reading your material to do something as a direct result, they're scanning your content and keeping the F-Shaped Pattern in mind is important. Additionally, web writers should take advantage of web features, like links and html....sounds pretty basic, really, but there are so many sites that just write for print and then post their documents in pdf format. They make is seem like providing a link to Adobe downloads for Adobe Reader is enough. It's not. It annoys readers if you simply post PDFs. Take for example, this NJ town's website. I realize this is a small-town website and they may not have many resources to beef up their website, but between their menus that make it difficult to find information to the fact that when you do find it, it's just pdf launching.....it's enough to make a person move to a more web-savvy town... (Not really....Maplewood is quite nice.)

Navigation is another thing web writers need to keep in mind. They may not be designing the website, but they should keep in mind how users will return to the content from the hyperlinks they provide, for example. Although print documents may have navigators through a table of contents and index, it's a different layer in the web.

Keeping your audience in mind for print materials means putting together a nice table of contents and index (for larger documents) as well as using clean headings and titles. Some of this is similar to the web, but as we can see, this is done differently - from making your website findable through relevant keywords (and meta tags as well) to formatting it in a way that different audience's needs may easily be presented without being overwhelming.

Social Bookmarking

Over the past few years, the web has gotten...well...a little more ......"social." You may have heard the term, "Folksonomy" bantered about in Web 2.0 discussions. What is Folksonomy? As per Folksonomy.com:

A folksonomy is an Internet-based information retrieval methodology consisting of collaboratively generated, open-ended labels that categorize content such as Web pages, online photographs, and Web links. A folksonomy is most notably contrasted from a taxonomy in that the authors of the labeling system are often the main users (and sometimes originators) of the content to which the labels are applied. The labels are commonly known as tags and the labeling process is called tagging.

I think that folksonomy generally describes the natural progression of the web -- in Web 2.0 currently and in the near future and eventually towards the realization of the Semantic Web. But, what are some of the tools that are used in Web 2.0? There are photo sharing sites, social bookmarking sites, blogs, wikis, etc. The practice of folksonomy enables users to tag various sites, blogs, etc. and share them with the world. I'd like to take a moment to explore Social Bookmarking.

Social Bookmarking is a method of marking a website and providing tags/labels that describe the website's contents. There are sites that are only in the business of bookmarking; del.ico.us, reddit.com, digg.com, among others. I took a look at del.icio.us, and you can find my bookmarks at http://del.icio.us/cr6. The sites I chose have to do with interests that are close to me - technical writing/communication and grad school -- as I'm currently enrolled in the MS -PTC (Professional and Technical Communication) program at NJIT. So, the sites I bookmarked have to do with issues of interest to people in the MSPTC program, and technical writers and communicators. Things like usability, help systems, writing, and design.

I can also search del.ico.us for bookmarks other people have set, by adding specific people to my network or by searching by keywords. So, if I search for "technical communication," I'll get sites that other people in the network have bookmarked and tagged with technical and communication. I noticed that when I did a search for "folksonomy" on Google, very high up on the list in the search results was a link for"Pages tagged with 'folksonomy on del.icio.us." Social bookmarking is easy enough to do, and keyword searches yielded some helpful results. So, let's examine the pros/cons of social bookmarking.

Pros:

• Can be used to offer useful bookmarks to a group of specific people (e.g., people in your school, class, work team, etc. It becomes more useful than a general web search when bookmarking is utilized in this way.
• It takes advantage of your "web-peers" knowledge of the subject matter you're interested in -- rather than the author of the website plugging in keywords in the code so you'll get a hit on their site in your searches. The folksonomy of this method may make your search results more useful. You can also get a ranking to see how many other people have bookmarked certain sites.

Cons:

• People who want you to find and bookmark their website may spend a lot of time creating the illusion that it's high ranked by bookmarking it themselves among a network of people that work for them in some capacity.
• People don't always tag sites with the same keywords, including spelling/typos. This makes finding some of the useful bookmarks a little harder.

Overall, I like the idea of sharing and allowing web users to become "folksonomists" rather than allowing the web "taxonomists" be our only guide to searches on the web. But, I can't help but wonder, what makes a web user better than a website developer at tagging the site? Wouldn't the web developer have even more of a vested interest in adding the right tags and getting the site listed in a way that the highest number of people who are interested in it will find it? And, as social bookmarking takes off and more and more people join it, won't it just be like.....searching the web? I'm not really buying the notion that web users will help direct me better than the web developers/authors. However, I can see how this is a fantastic way to share your bookmarks with a specific group of people (e.g., work group or grad school group) - as a team of people, they have a vested interested in contributing and making useful judgements about how to tag a site.

What do you think about Social Bookmarking?

I am cr6 on del.icio.us

Add me to your network