HelpScribe Technical Writing

Man versus machine | If John Henry was a technical writer

noreply@blogger.com (Craig) — Thu, 01 Mar 2012 23:30:00 +0000

There's no use arguing against the notion that content management systems, automation scripts, and fancy tools can make a technical writer more efficient. Case study after case study drives that point home clearly. However, there will always be times when a fly-by-the-seat-of-your-pants approach, powered by sheer effort and rapid decision making, can win the day.

The question is knowing when to use such an approach.

Consider John Henry. The folk tale presents Henry as a steel driver who worked the railroad lines. His strength and pace were legendary; he could tunnel through rock and drive railroad spikes faster than anyone working the rails.

Like the modern technical writer, Henry came face to face with machines that were designed to make his job more efficient. (Or, in his case, irrelevant).

John Henry wouldn't bow to the machines. Convinced that he was faster, he challenged the new steam-powered drilling machine to a race - his mighty hammer against the machine's relentless pace. And, amazingly, he won.

But it killed him.

Technical writers face the same risk when they let pride, denial, or even fear lure them away from automation, content management, and other time-saving technologies.

So why is John Henry's manual approach so appealing?

Not all jobs are a good fit for automation. For example, implementing a content management system can be costly and labor intensive. Writing automation scripts may require assistance from programmers. And, a formalized documentation process can be overkill for small projects that don't fit neatly into a pre-planned workflow.

In some cases, you may be better off just sitting down in front of your keyboard and pounding out some documentation in whatever format feels the most natural.

Before you dive in, here are some guidelines that may help you in deciding whether to trust your established tools and processes, or your intuition and strength-of-will.

Size: How big is the project? Large scale projects, with many pages of documentation or many discrete topics, will benefit most from automation, content management, and a formalized process. The efficiency gains from tools and processes are increased by the sheer scale of the project. Small projects, on the other hand, might not be worth the setup time required for a formalized approach.

Consistency: Does the project involve many similar chunks of content? If so, repetitive tasks can be automated, saving you time. However, if you are working on many bits of content that are relatively different, you won't find much benefit from trying to automate repetitive tasks.

Collaboration: Are you working with a team? If so, a formalized approach will ensure that you are all producing content in a consistent manner and of consistent quality. Using the same tools and processes makes sense for collaborative documentation. However, if you are flying solo, you have less reason to worry about structure. Just be sure to take careful notes when flying by the seat of your pants, in case you have to re-visit the project at a later time.

Standardization: Does your output need to fit specific standards, or work in a specific environment? If so, you'll want to follow a process that ensures meeting those standards and use tools that generate standards-compliant output. If the output doesn't matter, you have more freedom to follow your customer-focused intuition.

Winging it isn't always a bad idea. Just be careful. Machines, automation, and technology can make you much more efficient in many situations.

Consider carefully whether a John Henry approach makes sense given the requirements of the project. If so, feel free to swing your mighty hammer with liberty, and win the day.

The tools are secondary to the message

noreply@blogger.com (Craig) — Thu, 18 Aug 2011 04:24:00 +0000

A few weeks back I was introducing my 10-year old son to the art of computer programming. We were dabbling with an old version of BASIC, which he found both fun and fascinating; he could make games, draw graphics, and process input from the keyboard with just a few commands.

All was going well until my memory failed, and I couldn't remember the syntax for parsing string variables. (They say the memory is the first thing to go.) The help in the compiler / editor wasn't as thorough as I needed and the examples were too abstract to fit our code.

My son waited patiently while I stared blankly at the screen, hoping my synapses would reconnect. They didn't.

Fortunately, I own a heavy printed manual on the particular flavor of BASIC that we were using. I pulled it out and blew off the dust. I flipped to the index, found the section on string variables, and skimmed the chapter. Sure enough, it had detailed examples that clarified the situation. I wrote down the code we needed and my son typed it into the editor. He compiled the program and watched with excitement as it lit up the screen. Success!

What's interesting is that...

The answer to our particular question wasn't stored on a help server.
I didn't find it via a search engine.
It likely wasn't written in XML, or even SGML. (The book was printed in the early 80's).
Social media wasn't part of the development process.
No help authoring tool was involved in it's creation.
It didn't have a mobile CSS attached.

It was just words on paper.

It could have been written on rice paper and written with a quill pen. But it was the right words on paper. The words I needed.

Technology is amazing. In fact, I'm a strong believer in Buckminster Fuller's notions of ephemeralization. However, the flip side of ephemeralization is that as technology becomes more complex, human life should become more simple. As I sit in front of a computer each day writing code to make our publishing processes more efficient, a part of me (the Luddite part) keeps my ambition in check.

"Just words on paper," it says.

So, how does this apply to technical writing?

Just focus on picking the right words; let the technology take care of itself.

Capture video from your screen | tools and best practices

noreply@blogger.com (Craig) — Sat, 23 Apr 2011 01:01:00 +0000

Would you like to learn how to effectively capture video from your screen and create professional output? Such videos make excellent teaching and marketing tools, and they are becoming a standard means of web-based communication.

In this post, we'll cover best practices for producing an engaging screencast and talk about tools for getting the job done.

What we'll cover:

How to give your screencasts a professional feel
How to structure your content for optimal engagement
Tips for focusing on key concepts
Ideas for simplifying the capture / recording process
Free and paid tools for getting the job done

Adding a professional touch to your screencast

Before you begin recording, take some time to look over high quality screencasts and get a feel for what makes them attractive and engaging. Often, subtle techniques are all that is necessary to give your screen captures a professional edge. Well-executed animation, text effects, and presentation will help to keep your viewer from losing interest; just don't go overboard and create confusion.

Whether your project is for instructional or marketing purposes, a dynamic presentation will draw in the viewer's attention and help them to absorb the message.

For tips, check out How to Screencast Like a Pro. It includes tips for...

Increasing visual clarity
Capturing quality audio
HTML 5 and mobile video
Animation and layering for visual impact
Integrating popular tools such as Camtasia and Powerpoint

Now, let's talk about best practices...

Planning your content

When you plan your video, consider the attention span of your viewers. The longer your video, the more buy-in you'll need from viewers in order to keep them focused.

For longer conceptual screencasts, be sure that you include an introduction that tells the viewer what benefit they will gain from watching it to the end. Use your marketing skills here; no matter how useful your content is, you'll need to convince the viewer that it is worth watching.

For shorter screencasts, an introduction may not be necessary. In fact, viewers who are expecting short, quick demonstrations might not sit through your introductory content.

Create an outline of the major concepts you wish to convey. This outline will guide you in rehearsing the steps you will capture.

Many authors find it helpful to create a storyboard that shows rough sketches or mock-ups using actual screenshots from the software. These screenshots can be juxtaposed with the text content that explains them, whether you plan to show the text on screen or record it as audio.

The more detail you add to your notes, the less trouble you will experience when you actually begin recording your video.

Practice makes perfect

Now that you have your key concepts nailed down in the form of an outline or storyboard, you should practice your presentation.

Without opening your screencast software, go through the steps that you will demonstrate to viewers. Try to perform them exactly as you will when you begin recording the screens.

Practicing in this manner will help you avoid any mistakes. You're likely to have a few brain lapses, or visual "uh..." moments, the first few times through. Keep practicing until you nail the presentation and can demonstrate the entire process smoothly. Mistakes are easy to work around when you are just practicing; they are much more troublesome if you try to edit them out of an actual recording.

If you are recording audio, practice that as well. You can always add the audio track later, but speaking the process out loud will help you stay focused on the steps you wish to demonstrate. Also, it will train your auditory senses so that you'll remember your lines instead of stumbling over them when you do record the audio.

Preparing for your recording session

Before you begin recording, you'll need to set up a few things.

First, take a close look at the software applications that you will capture in your video. Focus specifically on the toolbars, menus, and other customizable interface features. Do they appear exactly as your viewers will see them when they launch them on their own PCs?

Try to set up your application so that it accurately mimics what a basic user will see (unless you are targeting advanced users). Doing so will reduce confusion and make it easier for the viewer to follow along and actually perform the steps in the same way you demonstrate them.

Now, take a look at your desktop, and apply the same principles. If you switch between applications in your video, your OS desktop will likely be visible. Are there any icons or desktop backgrounds that you do not want the viewer to see? Fix them before you get started.

Test your audio equipment also. Is your microphone set at the appropriate volume for recording clearly? You may need to find an area without a lot of background noise and practice mic placement to get a clear recording of your voice. Don't forget to keep a glass of water nearby in case your throat gets dry.

Last of all, check the settings in your screencast software. Are the project settings appropriate for the video you are about to create? Check the screen capture area, project titles, and other settings. Getting these right at the beginning could save you a lot of trouble; you don't want to re-record an entire video because your settings were wrong.

It's go time!

Relax. You've practiced this before, and you know the material.

Click the Record button, double-check that the screen capture area is correctly positioned, and move at a steady pace through the process you wish to demonstrate.

Aim for a moderate-to-slow speed. Mouse movements should be gradual. If you plan on using text captions, you'll want to give the viewer time to read those captions. Often you can adjust the timing during editing, depending on your software, but the closer you come to getting it right the first time, the easier editing will be.

When you are finished, hit the Stop Recording button and test your results.

Now, play back your screencast.

Does the pacing feel right? Are there any areas where you captured something unintentional, or where the software failed to capture what you wanted to demonstrate? You may need to go back and record additional slides and insert them where appropriate. (This assumes your tool is slide-based, like Adobe Captivate. Some tools produce a single video stream that makes such editing more difficult.)

Keep adjusting your output until you get the desired results, and then have others review your work.

Tools for capturing video from screen

Adobe Captivate - Part of the Technical Communication Suite. Captivate is a robust, slide-based tool that allows you to edit slides on a timeline, insert text, and more. It is one of the more expensive tools for recording screencasts, but produces very professional results. (It's what I use.)

TechSmith Camtasia - Another industry standard tool for producing high-quality results. Camtasia functions differently from Captivate, so you'll want to pick a tool that fits the type of projects you wish to create.

DebugMode Wink (Free!) - A freeware tool that offers robust features for screencasting. Handles audio and produces multiple output formats.

If you follow these guidelines, you should be producing high quality videos in no time.

See also:

An announcement you won't want to miss...

noreply@blogger.com (Craig) — Wed, 20 Apr 2011 01:53:00 +0000

I'm excited. (That doesn't happen often.) Wait a bit, and I'll tell you why, but first some back story...

A few weeks ago, I was approached by fellow technical writer/blogger (and all around great guy) Arnold Burian. He said he was launching an online community for technical writers and was hoping I'd help out as a site admin.

"Heck yes," I said. Or something along those lines. He obviously knew I had a weak spot for such projects.

In a very short time, Arnold had thoroughly researched community platforms, domain names, and the obstacles we were likely to face in bringing people into the community. I offered what advice I could.

In the following days, I watched him bring Technical Writing World to life.

The result was an attractive community website with rich features and intelligent design. I was immediately impressed.

I logged in, created a profile, and started to get a feel for things. The site felt sticky, like a community should. It pulled me in. The site was filled with relevant content that would engage technical writers; in fact, I couldn't help thinking how great a hub it would make for people who wanted to stay in contact with fellow professionals and up to date on the latest news. But, most of all, it felt friendly enough to bring writers out of the void and make them feel at home.

We started to spread the news via Twitter and other channels. And here's the exciting part... people started showing up!

Our community grew... 10 members, 20, 30, 40... in just a matter of days.

And they didn't just show up; they added profile pictures, made friends, started discussions, and made themselves at home.

That's what I like most about Technical Writing World. I feel at home. I can let people know that I've had a hard day at work, ask them for feedback, or just share a laugh with fellow professionals in a casual environment.

It isn't about the website; it's about the people.

There's always room for another community of like-minded people getting to know each other.

So...

If you haven't checked out Technical Writing World, give it a try. Create a profile, make some friends, and get involved. I think you'll quickly feel at home and want to come back.

And we'll all be there to welcome you.

-Craig (when you create your profile, send me a friend request)

What technical writers and kindergarten teachers have in common

noreply@blogger.com (Craig) — Thu, 17 Mar 2011 11:03:00 +0000

Do you remember kindergarten? Standing next to your little wooden desk reciting the Pledge of Allegiance before you slather yourself in finger paint? Eating Twinkies in a room full of screaming little people who can't wait for recess? Talking constantly and watching the kid next to you pick his nose while your teacher patiently recites the ABC's?

Well, technical writing is a lot like teaching kindergarten. Sure, your audience wears grown-up clothes and has likely swapped the Twinkie for a danish, but deep down, they are still waiting for recess.

Let's take a look at some of the struggles and concerns that you share with the ever-so-patient kindergarten teacher.

Warnings matter - Kids will eat the glue

Your users will find novel and dangerous ways to use your products. They will open the box, make immediate assumptions (what fits where, what can double as something else, what tastes good), and start cobbling things together or using them in a life-threatening fashion.

Warning labels are essential. Your users aren't dolts; they are just busy people who don't always have time to read a well-crafted set of instructions. So, they aim for efficiency and try to guess at how things work. Do them a favor, and find a way to warn them not to eat the glue.

Short attention spans

If you had a dollar for every time a kindergarten teacher said "Pay attention," you'd be very wealthy indeed.

Technical writers face the same struggle. If your content isn't gratifying, you'll be talking to yourself. That doesn't mean you need to entertain readers or dumb down the content to keep them from zoning out and drooling on their desks. Instead, you need to consider the business goals the user is trying to achieve and introduce your content by showing how it will help in achieving those business goals.

When you write your documentation, have a clear sense of the user's desired outcome. That way you will stay on track and avoid the inclination to over-document everything. Keep it relevant and goal-oriented.

Complaints, complaints, complaints

Mislead a kindergartener, and parents will call the office to complain.

Mislead a customer, and they'll keep calling back for Support. If they still can't figure things out, they'll stop using the product, and give it a lousy rating on the nearest product review website. They'll tell their friends how difficult your product is to use.

Try to anticipate any misunderstandings. Take the time to verify the accuracy of your documentation, and do some usability testing if possible.

Technical writers do not always have the chance to interact directly with customers, but keep in mind that your documentation has a direct impact on the impression your product makes. Always consider the marketing impact of your work.

If you receive complaints about the documentation, address them quickly, and be thankful for the feedback. It will result in a better product.

Rewards are everything

Kids love treats. Offer a kindergarten class a box of doughnuts for cleaning up the classroom, and they'll turn into a blur of activity and find every bit of scrap paper on the floor.

Your users also like rewards. Often they are engaged in tedious activities when they use your products, and would be happy to see some light at the end of the tunnel. Offer them a reward for reading the manual, completing the tutorial, etc. Perhaps you can offer points toward professional certification, or a printable certificate, or maybe just a cup of coffee. Better yet, write such great documentation that they will be able to complete the tasks at hand, and spend the rest of the day with their family.

Give the user something to look forward to, and that motivation will help them through the tedious path toward expertise.

Get What You Need Right Now To Become A Successful Writer

noreply@blogger.com (Craig) — Sat, 11 Dec 2010 06:06:00 +0000

This is a guest post by www.onlineschools.org.

It is nothing short of remarkable that the Internet has afforded us so much in recent years. The ability to effortlessly find information, work from home, or attend college classes online is just the beginning of all of the wonderful things that are now readily available through the Internet. For freelance writers, the availability of writing work has greatly increased over the past few years. Writers are in great demand by large online organizations looking to increase their web presence. The demand for writers who can succinctly and effectively write for Internet companies has increased due to the tremendous value they can now offer in areas such as search engine optimization. The more a freelance writer understands about SEO techniques and the better their quality of writing, the better they will be paid upon landing freelance writing contracts. Many writers have started taking online writing classes to better improve their writing skills and to advance their knowledge of search engine optimization techniques.

More and more, writers are finding that the skills they already possess can be used to earn a lucrative salary by writing articles, blogs, and web content for various Internet organizations. With a little refinement of their writing skills, and instruction in SEO techniques, freelance writers are able write for top online organizations. The writing sector is one of the fastest growing and best paying Internet jobs. With this in mind, why not consider a career as a professional writer?

So, you already have a wonderful command of the written English language and you want to become a paid writer. Well, you are nearly there. Possessing a love of writing is an absolute must for the professional writer. Couple this passion with a degree in technical writing and you are ready to embark on the spectacular journey of the freelance writer.

When it comes to improving your writing style and technique, not enough can be said about the necessity of continued education. In studying to become a professional technical writer, you will learn not only appropriate language use, but also the valuable techniques that can be implemented to increase website traffic. These skills are the ones that large online organizations are in desperate need of. When it comes to schooling options there are many to choose from. One of the very best options afforded a technical writing student is that of attending class online. Online schools offer tremendous flexibility in regards to class scheduling. Some programs require nothing more than assignment completion and class interaction via class message boards. These types of online schools for technical writing allow you to mold your schooling schedule to the demands of your own unique life. Not only do online schools offer the most flexibility in class schedules, they boast the very best teaching resources. Everything that a student needs to achieve success is provided through the Internet. From discussion board topics to resource links, and even multi-media instruction, online schools offer all the tools you will need to become a technical writer.

Whether you are contemplating a career change or looking to increase your compensation, there is no better way to accomplish all of this than by attending classes online and studying technical writing theory. Freelancing writing is one of the fastest growing job sectors on the Internet. Your ability to earn great money is only limited by your ambition and knowledge. Attending continued education classes online to obtain a degree will only serve to better prepare you for the exciting career opportunities that exist in the world of freelance writing.

Technical Writing Career Advice from 11 Experts

noreply@blogger.com (Craig) — Wed, 27 Oct 2010 02:11:00 +0000

A technical writing career is guaranteed to be filled with challenges. Technology is constantly changing, roles are shifting, and best practices are evolving. Wouldn't it be great if you could get the best minds in the industry in the same room and ask them for advice on how to be successful in such an environment?

With that in mind, I contacted the most influential technical writers I could think of and humbly asked them for an answer to the following question: "What advice would you give to a new technical writer who wanted to further their career?"

The responses were amazing and packed with useful information.

Here is what they said...

Scott Abel (http://www.thecontentwrangler.com/)

"Don't allow yourself to be limited or boxed into one type of 'communication' or another. Your title does not matter. In fact, don't be surprised if the job you are most suited for is not a 'technical writing' position. The fact is, the business world is undergoing a major paradigm shift and just now beginning to value the content we create as a business asset worthy of being managed efficiently and effectively. This means organizations are taking a look at the way we work -- the processes we use -- and optimizing them for maximum efficiency. They don't teach this important fact in school. Nor do they teach you how to be prepared for a job in today's market.

The skills most in demand are collaborative, structured authoring (which requires teamwork as well as the ability to write modular, context independent content chunks), content strategy (being able to match business goals to content creation, management and delivery tasks), and understanding of content standards like the Darwin Information Typing Architecture. Additionally, understanding and being able to design interactive content for today's hot mobile devices and eBook reader apps (think iPad, iPhone, Android) and mastering the art of social documentation and community management (making user assistance content interactive so we can quickly find errors, enhance quality, add missing content) are critical skills for the next generation of writers to posses.

Sure writing, punctuation, grammar, and rhetoric are important, but every college graduate is expected to have mastered these basics. To be successful -- and to differentiate yourself in this ultra-competitive global market -- you have to step outside the traditional 'writing' role and master the concepts that are important in all types of communication. Knowing your audience and the intent of your communication is key. Selecting the right communication method is also critical as some information is better conveyed in video, via audio, as an info-graphic or interactive simulation. It is not enough in today's world to be just a writer."

Mike Hughes (http://user-assistance.blogspot.com/)

"I come from a software development environment, and my advice is 'be an enabler,' that is, help your team meet its goals. By team, I mean the broader team of product managers, developers, QA, and fellow writers. If they need 'down and dirty' give them minimalist and good. If they need 'comprehensive, accurate, and this afternoon,' give them the most comprehensive and accurate document you can write this afternoon (better yet, find stuff you've already written). Too often, technical communicators get excluded because they turn into blockers, telling the team what they can't have.

The best compliment in any team environment is to become known as someone who makes the team better. Look for opportunities to use your communication skills to make that happen."

Alistair Christie (http://www.itauthor.com/)

"So you've got yourself a job as a technical writer. First off, don't worry about the job title. You won't spend all day writing, and a lot of the time the stuff you'll work on won't be particularly technical.

If you're working in a software development environment don't expect to get praised for how wonderful the documentation is - I mean ever. This might happen, but don't pin your hopes on it. Treat a lack of complaints about poor or missing documentation as your commendation. But don't let this discourage you. There are plenty of ways you can earn respect and become a valued member of staff. Working in a software development department you can be the representative of the end user in a way that the developers sometimes just can't - because they have their own particular way of thinking - and that makes you a really useful resource, so make it count. You can also get the sort of holistic, but detailed, view of the product set that few other people in the company can get. This is because you'll be working on lots of products and you'll always be looking at them from the point of view of the user. This makes you a useful go-to person for developers, product managers, sales guys and the marketing team when they need to know which product solves which problem, for whom, and how the products interrelate.

One of the biggest professional compliments you'll get is when people seek you out to ask you questions. Encourage this and grasp the opportunities that will come along to show people what you know. They'll be surprised. But once you explain why you know what you know, it'll make sense and they'll spread the word that you're someone who knows stuff.

As a technical writer it's easy to be anonymous. But do yourself a favour. Don't be."

Tom Johnson (http://idratherbewriting.com/)

"If you want to be successful, start a blog on technical communication and contribute to it regularly. Doing so will force you to read, ponder, and apply principles of tech comm to your everyday activities. It will keep you engaged and relevant. And it will make your job more interactive and fun, since you will see opportunities to analyze and reflect on the stories that happen to you everyday in the workplace."

Tom also recommended Laura Spencer's How to break into technical writing and his own excellent posts for technical writing students.

Gordon McLean (http://www.onemanwrites.co.uk/)

"My Top Tip - Ask Why. If you only learn to ask one question, ask why. Regardless of the task at hand, it's the most powerful question of all. Yes, even more powerful than 'who?' (knowing your audience is important I'm presuming you've already figured that out). Understanding why you are doing something, why you aren't doing something else instead lets you bring a level of business focus to your work.

We all have lots to do and rarely can we do it all, so ask yourself why, ask your boss why, ask your team leader why, ask your colleagues why, be known as the person that asks why (but do remember to ask how, what, where and when as well). You can extend the question into your writing as well; why does this work this way? why shouldn't the user do that with this product? why should the user do this with this product?"

Ellis Pratt (http://www.cherryleaf.com/blog)

"Look at how you can get some relevant writing experience that you can include on your CV. A lot of the open source software projects look for people to write the manuals. You could put yourself forward to join one of the writing teams. You could write procedures for a local charity. The ability to write well and to deliver on time are the two most important skills to have, so a portfolio of examples can help demonstrate this to prospective employers."

Bill Kerschbaum (http://wordindeed.wordpress.com/)

"When I first started technical writing, I knew of one overriding principle. Adhere to that, and I would excel as a technical writer--miss the mark, and my writing (and career) would be substandard. It's the same principle every technical communications student learns his or her first day: Make your writing accurate, brief, and clear. The Triune Goal of technical writing.

The ABCs of technical communication are the foundation of good tech writing, but a foundation is not a house. For a long time I made accuracy, brevity, and clarity my only goals in my projects. If I could keep it short, easy to read, and correct, I was happy--and so was my boss. But my writing wasn't great, and in time I got bored with tech writing. Eventually I began developing my exit strategy.

Then I realized that the ABCs, while necessary, aren't sufficient. I began to see room for creativity and personality in technical communication. I realized that user guides serve a role in marketing too, and my work had value beyond the numbered lists. My user guides could actually help a company connect with its users and reach new customers. Suddenly, design and creativity had a significant role in user documentation, and my goals expanded beyond the manual itself to the company as a whole, and even beyond the company to current and future customers. And so I revised my goals. Rather than pursue accuracy, brevity, and clarity I was now pursuing Truth, Goodness, and Beauty. Once I began that pursuit, my writing went from acceptable to exceptional--and so did my enjoyment in technical communication.

So don't mistake the fundamentals for the essence. The ABCs are a tool, not the goal, of technical writing. And the goal of technical communication isn't the user guide; that's just the means. Your goal as a technical writer reaches beyond the manual, and even beyond the company. And that kind of mission deserves all your creativity and passions.

Bonus: Read Selling the Invisible by Harry Beckwith. You'll see your role at your organization in a whole new light."

Scott Nesbitt (http://www.dmncommunications.com/weblog/)

"Remember that the technical part of technical writer is just as important as the writer part. Sometimes, it can be even more important. Writing isn't always enough. You need other skills to succeed in this profession. Like what? Obviously, knowledge of the tools of the trade. Don't forget knowledge of technologies -- ranging from operating systems to the languages and processes what you're documenting. Don't discount interviewing, either. You need to know how to draw information out of sometimes tight-lipped subject matter experts (SMEs). Having a knowledge of technologies helps; you can speak the language of the SMEs, and by doing that they'll take you a little more seriously."

Aaron Davis (http://www.dmncommunications.com/weblog/)

"1. Become an expert - Whatever technology, product or service that you're writing about, take time to thoroughly understand the details. Don't be afraid to ask a lot of questions. One lesson I learned early in my career was the value of "getting my hands dirty" by running, testing, and ultimately breaking the software I was supposed to be writing about. It taught me a lot. A "technical" technical writer earns respect from developers, project managers, and QA.

2. Learn and adapt - Diversify your skill set. Learn about new technologies. Learn the business that you're involved in, and understand how you provide value with respect to the strategic goals of the company. Take courses in different disciplines such as UX. The field is undergoing rapid change, and you need to learn to adapt and change with the demands of industry.

3. Become a good project manager - One key to becoming a successful technical writer is the ability to manage your own projects. You will be counted on to provide work estimates, develop project plans, and schedule deliverables. Take the opportunity to start cultivating good organizational and time management habits early in your career.

4. Don't become a tool fetishist - There are those in the profession who spend time arguing the merits of this tool versus another tool, or spend too much time learning the very granular details of a specific publishing platform. Avoid this behavior at all cost. Over the course of your career, you will be exposed to many different ways of authoring and producing documentation. Don't be stubborn. You will be using a new tool next year anyway.

5. Enjoy what you do - Why suffer doing something that you don't enjoy? Embrace and advocate your profession. Maintain a positive attitude. Have fun with it!"

Peggy Harvey (http://connectingtocontent.com/)

"My advice to a new technical writer is: Join the community. One way to do this is to volunteer with your local STC chapter (whether or not you're a member of STC), but there are other ways as well. Twitter holds a wealth of information for technical communicators. Follow the #techcomm hashtag and you'll be introduced to a world of content that ranges from debates on the use of rhetoric in technical documentation to how to apply DITA tags in a structured authoring environment. Twitter is also a great way to network with other technical communication professionals locally and internationally, which can lead to job leads and career advancement opportunities."

Julie Norris (http://www.2morodocs.com/)

"Stay current. Read. Observe. Participate. Dream.

Stay current with new technologies and methods. Choose a secondary subject in which to develop expertise, such as social media or usability. As far as skills go, I would say to absolutely learn HTML/CSS and XML. I’d also suggest basic database design. Staying current is, to me, the most important consideration.

Read everything you can get your hands on. You must keep up. Also, you never know what you may end up writing about and documenting, so look at everything.

Observe what’s occurring in technology and business in general to try and keep up with and anticipate trends. Keep an eye on marketing for social media developments. See what’s happening in the world, particularly with the ways people share and obtain information.

Participate everywhere you can. It’s a social, interactive world now. The days when the writer essentially worked alone are over. These days, everyone is involved in creating documentation. So join in as many conversations as you can. Learn how different options and formats work. Share information, learn from other writers, from users, from everyone.

Dream and imagine what’s possible. Work to turn your ideas into reality. The industry - as well as most - is in a state of upheaval due to demographic and technological changes. Much is being built (or rebuilt) from scratch. This is your time. This is your opportunity. In the 20+ years I’ve been in the industry, I’ve never seen a more exciting time. So dream big. Share your ideas. Experiment. Jump in and help shape the future of tech comm. Welcome aboard!"

And there you have it. That's an incredible amount of information to absorb, and it's pure gold. I plan on re-reading it many times myself because I can see the relevance to my own career.

Please visit the websites of these experts and subscribe to their feeds. I guarantee you will find a treasure trove of valuable insights that can be applied to your daily work.

To all contributors: Thank you so much for taking the time to share your wisdom. You truly are an amazing bunch of people and I'm inspired by the level of sharing and support you offer to the technical writing community. I know that HelpScribe readers will appreciate it as much as I do.

6 ways to improve your help authoring workflow

noreply@blogger.com (Craig) — Wed, 29 Sep 2010 22:00:00 +0000

Technical writing isn't just about producing documents -- it is a business function. For most of us the ultimate goal is to increase the overall profitability of our organization. By increasing the efficiency of our help authoring process we can be more productive, reduce costs, and maintain our sanity by automating tedious tasks.

Here are six ways to improve your help authoring workflow.

Use snippets - Any time you see a similar section of content in multiple topics, consider converting it to a snippet. That way you only have to update the content once to have those changes flow to all topics that include the content. If you use MadCap Flare, check out the Snippet Suggest feature in Analyzer.
Create online schedules - Use a collaborative scheduling tool so that everyone can stay updated on deadlines. Create a schedule for your project, send a link to all stakeholders so they can approve the schedule, and then create reminders for all deadlines (review dates, delivery dates, and so on).
Streamline reviews - Use document management software and Adobe Acrobat to facilitate reviews. Document management tools allow you to upload documents to a server, route the documents to reviewers, and track revisions. Acrobat allows multiple reviewers to make comments in the same PDF file, and you can print a comment summary when it's time to incorporate the changes.
Automate your help delivery process - Some HATs, like RoboHelp, offer a command-line option for generating output. You (or a tech-savvy coworker) can author a shell script or BAT file to launch your HAT's compilation process, prepare the output files for delivery, and copy them to your QA server or delivery location. You can automate the archiving process in a similar manner. WinZip offers command-line features for zipping up your project files so they take up less space in your archives.
Create email templates - If you are constantly emailing others to assign reviews or inform them that help files have been delivered, consider creating email templates that contain boilerplate text for each kind of message. Not only will this save you time, it will also remind you to include all of the important details. (I picked up this trick from a savvy manager.)
Share with others - By sharing the scripts, templates, and other time-saving tools with others in your department, you can increase the overall productivity of your entire team. This is a great way for technical writers to directly improve the company's bottom line and leave extra room in the budget for better tools and fun stuff like catered lunches, expensive coffee, and trips to the bowling alley.

Hopefully these tips will help you spend less time struggling with your help authoring workflow.

Small business information management strategies

noreply@blogger.com (Craig) — Sun, 26 Sep 2010 21:23:00 +0000

The amount of information modern businesses collect and distribute can be overwhelming. Even for smaller businesses, poor planning can have a negative impact on efficiency and scalability. By creating a solid small business information management strategy ahead of time, organizations can improve productivity and profits on a daily basis. Here are some tips for building such a strategy.

Information architecture should be scalable; by building a strict architecture, management over the long term becomes easier. Such a system will take more time to develop, but should lead to increased efficiency.
Small businesses often have limited resources; also, they often have less information to manage compared to large corporations. They should choose tools appropriately. Enterprise-level content management systems and similar tools will likely not be cost-efficient, especially when maintenance is considered.
Decision making tools, such as flowcharts, can help people react to situations without the interference of judgment and emotion. Take the time to develop these tools if they would be beneficial to your workflow.
A formal process for documenting new business information and categorizing it will improve retrieval. Such a process should be built upon a solid architecture. Spend a bit of time researching metadata and consider how to categorize your information so that you can generate accurate reports to ease management.
Information security policies should be set in place at the outset. Limiting the availability of information to those who need it can reduce long-term management requirements. Key issues are securing information that is only appropriate for certain audiences, limiting the ability to alter information to only approved individuals or groups, and limiting information loss.
Archiving and other preservation concerns should be addressed by the architecture and tools, and enhanced by writing policies and procedures. Automating the archiving of documents builds additional safety into the overall information management schema.
A small business can often model larger organizations; however, they should watch for architecture elements that will be inefficient and unnecessary considering the scale of their day-to-day operations and overall information needs.

Remember, the overall goal is to provide information to those that need it in a timely and efficient manner. The information management process should be as automated as possible so that your small business can operate more profitably.

Which kind of technical writer are you?

noreply@blogger.com (Craig) — Thu, 23 Sep 2010 22:47:00 +0000

When you work in a large technical writing department, it becomes very obvious that we all have different strengths and weaknesses. A great manager will hire writers with different skills to increase the overall effectiveness of the team. So, where do you fit in?

The Writer - You wait for enhancements like a kid watches for Santa on Dec. 24th. When they arrive, your word processor barely manages to stay one step ahead of your fingers and the carpet between your cubicle and your SME's loses another layer. Grokking the new features and turning them into instructions is what you do best, and if you weren't a technical writer you'd probably be a teacher or trainer. Specs? You're on it!

The Editor - You are an expert at slicing and dicing shoddy content and turning it into clear and concise text that flows like honey on a hot biscuit. Your waste basket is filled with empty red ink pens, and your inbox is filled with review requests because you've built a reputation for turning rough drafts into works of art.

The Techie - You go where others are afraid to tread... under the hood of your complex authoring tools. When things break, people knock on your cubicle door. The boss wants a custom ASP page for gathering feedback on server-based help? You offer it up the next day, including a back-end database and reporting tools. Easy as pie, as long as the coffee pot remains full.

The Socialite - You are the information highway for your department. When enhancements creep into the software, you know about it ahead of time because you work out with the developer and watch her pets when she's out of town. The team is having trouble getting feedback from a product manager? Not anymore, she's already on your Christmas card list and smiles whenever you knock on her door. You are a master networker and you never eat alone.

The Project Manager - You've never missed a deadline, thanks to your cross-referenced Gantt charts and systematic approach to getting the job done. You grease the wheels and keep productivity running on high at all times. Delays? Not on your watch. As long as your email software stays up and running, business will keep on rolling, because Organization is your middle name.

So, which kind of technical writer are you?

Technical writing unchained - a custom approach to help authoring

noreply@blogger.com (Craig) — Thu, 23 Sep 2010 00:15:00 +0000

After a decade of writing documentation for high-quality products using robust authoring tools, I've often wondered... what approach would I take if I was doing this just for fun, with no restrictions? What if help authoring was my hobby?

It's a rather insane idea: technical writing as entertainment. But I haven't hit my head, or quaffed one slushy too many (although I've suffered many cases of brain freeze). Remember the personal computer industry 25 years ago? When computer users were geeky college kids who spent three hours typing in machine language to make a ball bounce across the screen? It was about fun. And where do you think all of those Unix MAN pages came from? Hobby computer geeks writing for the sheer fun and glory.

So, let's say I'm building a help project for fun. How would I equip myself?

Right off the bat, I'd throw out my HAT. (Sorry, the rhyme was completely unplanned.) Not because they are bad; in fact, robust tools are essential for multi-author environments where efficiency is key. But if I'm doing this on my own, I don't need the headaches that come with an integrated tool set, nor could I justify the expense. (It isn't that fun of a hobby.)

Why choose small tools? Big programs tend to crash more. (That's a generalization, but a good one, I think.) Small, specialized programs would allow me to author my help project without the hassles caused by all-in-one solutions. And I can get the tools for free.

All output features, such as navigation, I'd build myself.

My project would consist of a well-structured set of folders, similar to the output you get when you generate browser-based help.

I'd start by installing Notepad++, including a spellchecker plugin. Seriously, if I'm going freestyle, all I need are line numbers. Bells and whistles, drag-and-drop, and WYSIWYG tools are great if you're drinking the HAT kool-aid, but I've always preferred working under the hood. (Maybe that's why my help authoring tools crash often. You can't hot-rod them the way you can a 1970 Chevrolet and expect everything to run smoothly. I've tried, with only limited success. You can't just "bolt on" some extra subroutines.)

Next, I'd install Perl. Perl is like a Swiss army knife; when you need a can opener, it can get you pretty close. I'd use Perl for global search and replace, reporting, and for auto-generating navigation components, which I'll talk about in a bit.

Last of all, I'd install a link checker. Xenu's Link Sleuth is good, and produces very thorough results.

Now the fun begins. After editing my topics in Notepad++, I'd run a home-brew Perl script to auto-generate a collapsible table of contents based on topic titles. A meta-data tag embedded in each topic would tell the script whether to include a topic, and where to put it.

I'd hard-code my index, or build it from meta-data tags, but with careful planning and selection. There's no better way to do it. An index needs to be created manually in order to be really useful. Readers don't think like computers.

Here's where it gets interesting: Search functionality.

For search, I'd install the Google Adsense search tool. Why? Because nobody knows search better than Google, and their algorithm is incredibly advanced. It's like tapping your help project into HAL 9000 or something. People will find what they are looking for.

Also, this is a hobby project, so why not make some money from it to fund future projects? Awesome search plus free cash? I'm sold.

For analytics, I'd do the same. Google Analytics would let me fine-tune my keyword usage based on actual search behavior. That way I can optimize the findability of my help topics. Also, the bounce rate would tell me whether my content is really addressing the needs of users. (This can get tricky. See this post on using analytics for documentation for details.)

Last of all, for quick-and-easy compilation, I'd daisy-chain all of the Perl scripts into a Windows shell script or BAT file so I can build the whole kaboodle with a simple command.

That's it. That's how I'd build a home-made system for authoring help.

Maybe one day, in my vast amounts of free time, I'll give it a whirl on an open-source project. But I'm guessing others have blazed this trail already and still have the results archived on a floppy disk somewhere. If that's you, I tip my hat in your general direction.

The Boss hates your document! How to fix it

noreply@blogger.com (Craig) — Wed, 22 Sep 2010 00:14:00 +0000

You've spent the last month as a contract worker struggling with a tedious user manual. Finally, you create the PDF, hand it over for delivery, and head home with a feeling of satisfaction. But... to your horror and surprise, you find it sitting on your desk the next morning covered in red ink and a note from your boss.

What do you do?

First, don't panic. This often happens as a result of miscommunication, and can be cleared up without too much trouble. Technical writing requires a bit of political savvy, and now is the time to leverage your interpersonal communication skills. (Or, if you've joined the dark side, some shady tactics for tricky office situations. But once you go down that path, you can never return... Bwah hah hah!) Sorry, where was I? Oh, yes...

Bury your feelings of resentment, take a short walk, and then read through the comments. Are they sensible and straight forward? If so, incorporate the changes and redeliver the manual. If not, ask the boss for a meeting.

During the meeting, talk about what exactly when wrong. If there are major problems with the scope of the manual, be sure to get a clear sense of what needs to be changed before you leave the meeting. That way you can address those issues and produce a user guide that is closer to the mark. You don't want to end up in the same situation a second time.

If you disagree with the changes, don't be disgruntled. It's a job, and your boss has the final say. Finish the job and move on.

You may find that there is some doubt about the value of the manual. If you sense this is true, bring the issue up for discussion, but do it in an objective manner. Don't take it personally. Take some consolation from the fact that you did your best, whether the manual is shipped or not. Your job is important.

If the revisions requested by your boss will require further communication with SMEs, be sure to explain the situation to those SMEs openly. Ask them for a bit more time, and be flexible, because they are probably working under deadlines just as you are. A spirit of cooperation will help you get through the job.

Just keep moving forward and stay positive; you'll get through it. And when you finally finish the project you'll have an even greater sense of accomplishment and relief.

This simple trick can make your documents more engaging immediately

noreply@blogger.com (Craig) — Mon, 20 Sep 2010 23:00:00 +0000

Technical writing is generally boring. Not so much the process, but the documents themselves. We can plunge into an endless debate about whether writers should inject humor or other elements to pull readers in (I say Yes!), but maybe there's a simpler answer.

For example, there is a sure way to make technical documents easier to read without making them sound less professional. Novelists and poets are well aware of this strategy, because they focus relentlessly on style. What is this strategy?

Simple... vary your sentence length.

Long, monotonous sentences filled with technical details are mind-numbing. Why not break things up a bit?

Varying the length of paragraphs and sentences has a subtle impact on the attention of readers. It forces their brains to constantly adjust. Without this change in pace, the monotonous rythm of your content will lull readers into a coma faster than a hot toddy and a lullaby.

For example, let's look at the following sentence.

The archive feature allows you to store unused data collections in an efficient manner. Archives can be stored in multiple formats depending on several factors. These factors include the size of your data files and the storage devices available on your computer. Archived data can be retrieved at any time using the Restore function.

Seriously, that's boring stuff. Let's see if we can adjust the pace to make it easier to read.

Do you have unused data in your system? The archive feature can help. When you create an archive, your data is compacted and then stored to the media format that you choose, based on the size of your files and your available hardware.

Don't worry; you can restore your archived data at any time.

Ok, so it isn't exactly "Madame Bovary." But you get the point. You can supercharge a dull sentence without adding knock-knock jokes. All you need to do is experiment a bit with the length of your sentences and paragraphs.

Technical writing does not have to be boring.

7 tips for technical writing students

noreply@blogger.com (Craig) — Sun, 19 Sep 2010 15:18:00 +0000

Fifteen years ago, I was a sleep deprived student slogging my way through a technical writing program in hopes of finding a job. I didn't really know what it was like to work in the field; however, I knew I enjoyed writing and that my love for poetry wasn't going to help cover my college expenses. In other words, I was just stumbling through, like so many students. If I had to repeat the process, here is what I'd do differently.

Network heavily. University professors are well connected. A student can make valuable connections by demonstrating a willingness to learn and be dependable, and then asking professors for career advice and introductions to contacts. Professors are usually glad to help students who ask and put forth honest effort.
Work on projects. Assisting with any relevant project for the university, such as updating a website or editing student resumes, can help you build your resume. Focus on both skill development and creating a portfolio.
Connect via LinkedIn. Start making connections with other students and keep in touch with them. When you find yourself looking for a job, these contacts may come in handy. Don't just network with fellow writers; also keep in touch with computer science and engineering students, because they might be the future product development managers who need your services.
Take advantage of resources. Universities have great libraries, computers with network access, writing labs, career centers, and other facilites that can really help you with career research, job hunting, and building your skills. You are paying for them, so why not make the best use of these resources?
Attend industry-related events. If your English department hosts conferences, invites professional speakers, and so on, be sure to attend. These events will expose you to new ideas from professional technical writers.
Don't focus on the degree. A degree might get you a job interview, but it is your passion and knowledge that will get you hired and propel you through the ranks. If you are only there for the paper, you are wasting your money. When you graduate, you will be one of many job seekers with a degree. What sets you apart? Focus on building your expertise and developing a reputation as a professional.
Don't stop learning. Just because you've completed your degree doesn't mean you have learned everything necessary to be effective and stay relevant. Take advantage of online technical writing programs to continue building your skills after college. Also, get involved with industry associations such as the Society for Technical Communication so that you can stay up-to-date on industry trends.

You put WHAT in your user manual?!

noreply@blogger.com (Craig) — Thu, 02 Sep 2010 01:56:00 +0000

Ok, so I cheated and chose a title for this post that would grab your attention. But there's a good reason. You see, writing a user manual is a tricky business. You have to inform your customers in an accurate way, and help them struggle through any tedious tasks.

But...

That can't be all you do. If you don't put in any effort to engage your readers, you may just lose your most important customers.

Think about it... most of us are just putting out fires. We get into the habit of writing documentation that has a highly professional (ahem... "boring") tone, and we write it in a very disconnected manner because most users just want a quick fix. I've been guilty of promoting this approach myself, because it does meet the needs of many users.

However, it doesn't meed the needs of the most important users of your products.

For example, I know a certain kid who loves video games. When he gets a new game, the first thing he does is read the manual from front to back. That way, when he begins playing, he already has a full understanding of that game. It immediately increases his ability to play the game to its fullest, and appreciate it, even if the game is complicated. In other words...

...he becomes a power user.

...he becomes a product evangelist.

...he becomes a loyal customer because he experienced the full potential of the product.

If a user manual isn't written in an engaging manner, how many potential power users are you sacrificing? Sure, you'll get some people back on track using basic features, but will any of these users ever develop a full understanding of more complicated features without reading overview information?

Give users a full and engaging story to understand. Or expect that they will only ever have a partial understanding of your product, and less loyalty when a competing product crosses their path.

If you enjoyed this, you might also like: 22 tips for writing software documentation users will actually read.

Technical writing and efficiency

noreply@blogger.com (Craig) — Thu, 26 Aug 2010 23:48:00 +0000

Writing technical documents is a complicated process. Even more so if you work in a large department, producing many documents for multiple products. Working efficiently is important if you want to stay on top of deadlines and avoid pulling your hair out over unnecessary complications.

However, sometimes process improvements are a double-edged sword. While a change in your process might make one aspect of your workflow more efficient, it can often increase the workload in a different area.

Let's say you have several projects in process, and you devise a system for tracking status and metadata about those projects using a fancy Excel spreadsheet. As long as you keep the information in the spreadsheet up-to-date, it is useful and helps you stay on track for hitting deadlines.

But what if you slip and forget to update the spreadsheet? And what if the amount of information you are recording in the spreadsheet becomes tedious to keep up-to-date during a last-minute rush to meet a deadline? In technical writing, a lot can happen during the few days prior to a product release.

Unfortunately, the work necessary to maintain any system can offset the efficiency and peace of mind you gain from that system.

So, before you implement a complicated system for improving your workflow, ask yourself: "Is this really going to make my job easier? Or is it just adding to my workload?"

If you sense that it will increase your workload, don't just ditch the idea completely. Instead, ask yourself if you can reap the same benefits in another way. Perhaps you can come up with a different process that requires less maintenance.

For example, instead of using a complicated spreadsheet for tracking project details, perhaps you can embed such metadata into the documents themselves as hidden text. You're going to be working in those files regularly anyway, so the risk of failing to update that information is greatly reduced. Then you can run a macro or script to pull that data into an on-the-fly report any time you want. The need to maintain an external spreadsheet disappears, and you can still track the details that are important to you.

So the next time you try to make a process more efficient, be sure to consider the cost of maintaining that process. You want to spend your time writing manuals, not stressing out over a system that doesn't work.

Increase your income

noreply@blogger.com (Craig) — Thu, 19 Aug 2010 22:18:00 +0000

Part of the reason many of us become technical writers is because it offers high rates of pay compared to other writing jobs. Here are a few ideas for maximizing the financial rewards of your technical writing career.

Be the expert. Ask yourself what struggles your organization will face in the near future and over the long term. Use some free time to build your expertise in those areas so that you can be a major contributor. By guiding your team through such struggles, you drastically increase your value.
Consider a promotion. If your company offers upward mobility within your department, think carefully about whether you would want to take the job, and start preparing now. Write down a list of the skills and responsibilities such a promotion would require, and start proving your worthiness. If you aren't sure about the availability of promotion, or the responsibilities, ask your manager or HR staff. (Tread carefully though, so you aren't perceived as a threat to your superiors. Hopefully you aren't in such a dog-eat-dog environment, but it's worth mentioning.)
If your current position offers no hope for upward mobility, consider looking for positions that do. If you don't seek, you won't find. Look for companies that offer upward mobility and are a good match for your skills.
Further your education. While you don't want to be perceived as overqualified, statistics show that higher education correlates to higher income. Consider whether certification, an advanced degree, or a related degree such as computer science or engineering would increase your value; many online technical writing programs are available.
Volunteer for challenging assignments. Some roles are simply more challenging than others, and may require greater responsibility and more overtime. However, the rewards usually follow suit.
Consider freelancing. Building your own technical writing business can be difficult, but it can also be highly rewarding. In addition to working your own hours, you get the benefit of setting your own rates. Many freelancers start out doing side jobs in their free time until they build up a stable client base.
Write a book. The publishing industry is always looking for authors who are experts in cutting-edge technology. Authors usually receive an advance as well as royalties from book sales. Publishing is a great way to increase your income and build your reputation at the same time, and establishing yourself as an expert can lead to future offers and profitability.
Get involved in web publishing. Your ability to write content and deal with technical issues makes you a perfect candidate for running a blog or website. Such a site can help you build your reputation, land new contracts, and generate income from advertising, affiliate offers, or products that you create yourself.
Leverage social media as a networking tool. Connect with others on LinkedIn, Twitter, and other sites and build your reputation by contributing regularly. Doing so will help you stay informed about interesting projects, lucrative opportunities, and open positions that may not be posted elsewhere. As they say, it's not what you know, it's who you know. (Actually, I'd say it's about 50 / 50; this industry seems especially appreciative of knowledge.)

Hopefully these tips are helpful in maximizing your technical writing income.

How technical writing committees keep things moving

noreply@blogger.com (Craig) — Tue, 17 Aug 2010 22:25:00 +0000

How many times have you seen great ideas fall through the cracks as higher priorities steal your team's attention? Technical writing teams have to juggle a lot of priorities, and sometimes we have to sacrifice improving our process in order to hit deadlines. However, letting those great ideas slip away permenantly can be a big mistake over the long run.

That's why committees are so great.

Committees allow managers to delegate tasks, such as research or testing, to a small group of writers. Those writers can schedule regular meetings, draft goals, and ensure that progress is made in spite of the day to day work that eats up most of our time and attention. The committee can then report findings back to the rest of the team.

The effectiveness of technical writing committees depends on a few key factors.

Deciding which long-term goals are worthy of a committee. Especially for small teams, prioritization is essential.
Choosing the right team members for the committee. Project management skills will be necessary to keep the committee on track, and domain expertise is essential for making educated decisions. A balance of personalities and skills is essential.
Establishing a process for tracking decisions and findings, and sharing that information with the rest of the team.
Assigning and tracking To Do items for committee members.
Choosing a chairperson to schedule future meetings and keep things moving.

I've recently been involved on multiple committees and have found them to be very effective. Usually such work grinds to a halt when deadlines loom. However, having a regular committee meeting allows for steady progress and decision making in spite of a busy workload.

So, does your team have a bunch of goals that you can never find time to pursue? Perhaps you need to form some committees.

Turning document reviews around quickly

noreply@blogger.com (Craig) — Fri, 13 Aug 2010 22:06:00 +0000

Hitting deadlines can be a real hassle when document reviews don't go as planned. Here are some tips for getting reviewers to provide feedback efficiently.

Provide a documentation schedule, so that reviewers can agree to review deadlines beforehand. This gives reviewers a chance to warn you if they are going to be on vacation or otherwise unavailable. You can then adjust the schedule or ask if someone else can review the document instead.
Make the due date clear so that reviewers know how much time they have to return comments. Put the date in bold print on your signoff slip and review email message.
Use a signoff slip. Make it look official so reviewers will feel more pressured to comply with your review request and sign off.
Try to keep your list of required reviewers short. One key SME from each relevant department is good. If others ask to be added to the reviewer list, ask if they can be considered FYI (comments appreciated, but not required). Too many reviewers will make hitting your deadline impossible.
For multiple reviewers on the same team, ask them to share a review copy. That way you won't have to sort out conflicting edits. They'll be able to see what other reviewers have suggested and sort out conflicts themselves.
Exclude any documentation that hasn't changed from the review. That way reviewers can focus on the content that needs the most attention.
If you must include all content, provide reviewers with a list of sections that have changed significantly.
Clearly indicate any questions that you have for the reviewers so you don't have to waste time following up later. Either embed and highlight your questions, or put them in a separate cover sheet in the review PDF or hardcopy.
If the review deadline passes and you still haven't received signoff from everyone, send out a follow-up message immediately.
If a reviewer doesn't respond to your follow-up email, send a message to their manager politely stating that you can't reach the reviewer and asking if someone else is available. (Careful, you want to keep things moving, but do this in a way that doesn't tick off the manager or the reviewer. Use your powers of rhetoric, your best Bill Clinton smile, and have some fresh-baked brownies ready.)
If a key reviewer is having genuine time constraints, follow up with the product manager about how strict your deadline is. If they've worked a few days worth of padding into that deadline, they might agree to let it slip if the reviewer is known for providing great feedback.
Use your phone if comments aren't clear. Or, crawl out of your hermit hole and go talk to the reviewer in person. The exercise and social contact will do you some good. Waiting for an email response can waste valuable time if you're trying to hit a deadline.
Some reviewers may request multiple reviews to verify that you have made the correct changes. That's fine if the schedule allows for it, but try to limit it to no more than two reviews.

Remember, technical writing is 50% project management, 40% politics, and 30% writing. (And 0% math, fortunately.) Anyway, try to stay on top of things and your reviews will be less stressful for everyone.

Related post: Technical writing and efficiency

Major documentation mistakes | Are you making them?

noreply@blogger.com (Craig) — Thu, 12 Aug 2010 22:13:00 +0000

Do you want to leave your users feeling confused and frustrated? Writing great documentation can be an uphill battle if you aren't aware of the pitfalls. Success depends on teaching the many skills consumers need to develop to become adept users of your products. Here are some common mistakes to avoid when writing your documents.

System based documentation

Be wary of documenting product features instead of tasks. Your users don't want to know to function of each component of your product. Instead, they need to know how to use these many components to complete actual tasks.

Often system based documentation is the result of engineers and developers providing content. Their job is to build features into the product, so it is only natural that they would write details about individual features. It is your job to take these detailed specs and incorporate them into procedures based on the tasks users need to perform with the product.

Lack of context

All procedures in your user guide should begin with a description of any prerequisite steps necessary for completing the procedure. For example, telling a user to click a button on a dialog is useless if they cannot find the dialog. You can use cross referencing if necessary to point them to any prerequisite instructions, but make sure the user has sufficient context necessary to successfully complete the task.

Poorly balanced content

Consumers will not all have the same goals when they read your user guide. Some will read the guide from front to back to develop detailed product knowledge before they start using the product. Others will use the guide as a reference tool, reading only the sections that they don't understand through intuition. You need to write with various types of readers in mind.

Be sure to include overview information and best practices for users who want to become experts. Also include reference information and granular content for users who are trying to troubleshoot a specific issue, or complete a single task. Try not to make assumptions about your audience; instead, base your content decisions on usability studies, personas, and actual data so that you meet the needs of all users.

Outdated or incomplete content

Schedule periodic reviews of your user guide, so that the developers can update any outdated content or fill in missing information. Products change; your documentation should change accordingly.

By scheduling regular reviews, you decrease the risk of misleading users. Providing inaccurate or incomplete documentation can destroy the credibility of your guide or even put consumers in danger.

Inconsistent structure or presentation

Presenting information in a consistent manner allows users to absorb content more efficiently. By establishing style and formatting guidelines and following them strictly, you help to reduce reader confusion.

Be sure to use styles to control the formatting of your paragraphs and headings. Also, present your chapters in a structured manner. Each chapter should be introduced and concluded in a similar way, so that the reader feels a sense of familiarity and comfort with the presentation of content.

By following the tips above, you should have a better chance of producing a helpful user guide. Try to stay focused on key tasks and on understanding your audience.

If you enjoyed this post, you might also like User guide writing tips.

Structured authoring | 10 questions to ease the transition

noreply@blogger.com (Craig) — Fri, 30 Jul 2010 00:38:00 +0000

If your technical writing team is considering a move to structure authoring, you'll probably want to answer some fundamental questions before investing in tools or a specific workflow. Here are some issues to consider as you plan for such a move.

Is a single requirement pushing you toward structured authoring, or are there multiple reasons such a move would be beneficial?
If it is a single requirement, are there other options that would help you meet that goal and be less labor / cost intensive? For example, do your existing tools offer features for content re-use that you haven't explored?
Is the amount of labor you will save by moving to structured authoring going to be greater than the learning curve, tool costs, and long-term changes in workflow?
How will you track content that is re-used? Do you have a tool to manage these blocks of content, or do you need to come up with a metadata scheme and a search process for finding that content at a later time?
Do you need to shoe-horn your existing content into strict topic types (DITA tasks, concepts, etc.), or would it be more cost effective to start with a generic topic type until you have more time to tear apart your existing content and make it more granular?
Is your content complex enough to warrant a move to standards such as DITA and DocBook, or would it be simpler to create a less-complicated XML / XSLT workflow?
Is your team prepared for the technical challenges of working "under the hood" with tools like the DITA Open Toolkit, or do you need a WYSIWYG-type editor that offers built-in support for structured authoring?
If you choose a tool with structured authoring support, does that tool produce the output formats you need (PDF, WebHelp, etc.), or will you need to do a lot of customization?
Is your existing documentation filled with custom formatting and functionality that will make a conversion to XML difficult? If so, can you eliminate some of these features for the sake of future portability and a simpler conversion?
What tasks can members of your team begin working on now, in preparation for the conversion? Testing whether trial versions of tools can import your existing documentation projects? Cleaning up content that isn't likely to convert well?

Moving to structured authoring can be costly and labor-intensive. However, asking the right questions first can make the transition much easier for you and your coworkers, and save you money.

10 reasons to stop printing manuals

noreply@blogger.com (Craig) — Thu, 15 Jul 2010 00:26:00 +0000

Is your company still producing printed manuals? If so, there are many reasons to consider converting these documents to an electronic format. For example, portable devices such as tablet PCs and smart phones have made it possible for technicians to access electronic how-to guides in the field.

Here are a ten reasons technical writers should consider eliminating paper manuals.

No printing costs: Ok, this is a no-brainer. However, it is also the most likely to improve your department's budget. Also, you can save a lot of trees and help your company become more environmentally friendly.

Rapid distribution: A PDF can be emailed instantly to anyone, and so can links to documents stored on a server. Also, technologies such as RSS can be used to immediately alert users of updates.

Easier and cheaper updates: There's no need to reprint the guide if you need to correct mistakes or make changes. Just update the electronic version and publish it to a server.

Consolidation of end-user information libraries: All of your technical documents, as well as other information resources, can be accessed by end users from a single portable device.

Elimination of archive space: Department archives can be moved from storage vaults to servers or fixed media, saving both floor space and money.

On-the-fly translation: End users can use software to translate electronic documents into various languages; this is not possible for printed manuals.

Better navigation: Try implementing a full-text search on your printed manual. (If you figure out how, let me know.)

Improved accessibility: Screen readers and other accessibility tools only work on electronic documents. To a blind person, your printed manual is useless.

Improved sharing and cross-referencing: End users can easily link to electronic documents, even specific sections, from their internal processes and procedures.

Crowd-sourcing and collaboration: If a user spots inaccurate information in a printed manual, you'll likely never find out about it. However, online formats such as wikis allow users to suggest changes easily and contribute new content based on their best practices.

Of course, there will always be cases where printed instructions are best. For example, instructions for setting up residential Internet service would be useless on a server; the user would not be able to access those instructions. Think carefully about the needs of your users and choose the best format.

Content reuse the easy way

noreply@blogger.com (Craig) — Wed, 16 Jun 2010 22:34:00 +0000

For years you've been hearing about how structured authoring and XML-based workflows can help technical authors reuse content more efficiently. By converting all of your topics to an XML standard, investing in a CMS, and building custom DTDs and XSLT translations, you can avoid having to maintain duplicate content.

The downside? Months of time invested in research, evaluation, and conversion only to be followed by a steep learning curve as your team adjusts to a new workflow. And then there's the price tag for the CMS, editor, and maybe some consulting fees to ease you through the difficult parts. Such implementations can cost in excess of six figures for larger organizations.

Does reuse have to be so painful?

In short, no.

The good news is that many technical writers can reuse content efficiently with their existing tools.

Quite a few authoring suites support features for content reuse. Under the hood, they work just like DITA conrefs or other forms of XML inclusion; you write some tagged content in a separate file, replace all instances of that content with a cross reference, and the HATT replaces those cross references with the full text when you generate your output.

For example, the product suites from Adobe, MadCap, and Author-it all allow you to reuse blocks of content across topics or documents. You can use snippets for duplicate content at the paragraph level, and variables at the word or phrase level. MadCap Analyzer and Author-it Xtend are particularly helpful because they analyze your documentation for redundant content and suggest reuse.

Such features are not available to most authors who have moved to a custom XML workflow; often these writers resort to memory for tracking content reuse. At best, they must invent complicated metadata schemes for finding existing content, and actively search the database when they suspect duplication. Why not let the tools do it for you?

Also, most of the HATT tools combine editing, project management, and publishing features into a single interface, and publish output that is user friendly for a technical communications audience. If your goal is to reuse content, why bother reinventing your navigation scheme using XSLT and purchasing a license for third-party search functionality? Stick with the tools that publish output you need, and reap the benefits of a familiar workflow.

Instead of revamping your workflow completely, you can spend your time focusing on how your content is structured and rewriting it for more efficient reuse.

I'm constantly seeing quotes about how people were able to reuse a large percentage of content by moving to a custom XML workflow. But doesn't that percentage have more to do with how their content is written than the tools and workflow they chose? If there is 80% redundancy in your content, you'll likely gain 80% reuse whether you choose the complicated home-brew XML solution, or just use the snippets feature in your HATT. It isn't about the tools, it's about the writing.

Before you invest major resources in a move to XML, consider whether reuse is your only goal. If so, maybe your existing tools will do the job just fine.

That said, there are situations where custom or standards-based XML solutions are optimal. For example, they offer a very high level of flexibility. Writing a custom XSLT transformation gives you full control over the appearance of your content. Also, standard formats such as DITA are highly portable if you need to change tools.

Don't just assume you need a custom XML workflow to gain the benefit of content reuse. Chances are you can manage duplicate content efficiently and lower your overall word count without sacrificing the robust features of a dedicated help authoring tool.

RoboHelp basics

noreply@blogger.com (Craig) — Sun, 13 Jun 2010 15:22:00 +0000

RoboHelp is an industry-standard tool for creating user assistance. Let's chat a bit about the basics of creating help with this tool.

Adobe RoboHelp is a topic-oriented tool. Each topic has an individual topic id assigned for easy reference and linking. You can view topics by ID or topic title in the Project Manager pod.

The best way to approach help authoring with such software is to first outline the tasks and concepts you need to document. For example, if you are creating documentation (help topics) for a software application, begin by looking over your specs or the actual app. What tasks can be performed? Create topic stubs for each. Also, create an overview topic with conceptual information to tie the tasks together.

RoboHelp Projects

When you create a new project, RoboHelp allows you to specify some basic settings for the project, including a default topic, navigation settings, and an output type. RoboHelp generates help in several formats; the browser-based WebHelp is a popular format because it uses standard HTML files. The AIR help format is becoming increasingly popular also. You can also create Flash Help, WebHelp Pro (server-based help), and print output for MS Word.

Navigation options include a table of contents (TOC), full-text search, glossary, and index. These are presented in a separate pane in the published output, so that users can view the navigation and topics at the same time. Most of the navigation can be altered with in-tool editors. The search is generated automatically when you generate your output.

During the setup of your RoboHelp project, you will choose options in the Single Source Layouts dialogs that specify your default output and the navigation settings.

After setup, you can access resources in your project using the Project Manager pod. This pod contains a list of all of the topics you have created, any images stored in the project, and the Table of Contents and Index entries that you have defined.

RoboHelp editor

RoboHelp features a WYSIWYG editor and a code view. This allows you to work under the hood when you wish. Also, there are several handy tools available for creating dynamic HTML effects and so on. In addition to written content, you can insert images, video, PDF documents, and other resources into your help topics. Some of these can be embedded directly, and others can be accessed via hyperlinks. RoboHelp tracks all of the resources in your help project using XML baggage files.

If you decide not to use the internal editor, you can specify a third-party editor. When you click a topic in the Project Manager, RoboHelp will open the topic in the editor you have chosen.

Output

After you create your project and write your topics, you can generate the project and view the output.

You can also link your help into the applications you are documenting. This is known as context-sensitive help, because you can link specific topics to the appropriate features in the application interface. RoboHelp offers several APIs for linking topics into your software applications. View the help topics in RoboHelp for details. In some cases you will need a map file to help you associate topics with individual GUI components.

You can buy RoboHelp as part of the Adobe Technical Communication Suite 2.

Technical writing skills that increase your value

noreply@blogger.com (Craig) — Wed, 05 May 2010 14:27:00 +0000

Technical writing is a challenging field because technology is constantly reshaping how we deliver information. By keeping up with these changes, you can increase your reputation as an expert and add value to your organization.

Let's take a look at some of the skills that you can develop to increase your value now.

Content management

Many technical writers are seeing an growing demand for content management skills. Organizations are dealing with ever-increasing amounts of technical information and are scrambling to find ways to efficiently manage it. Much of this information ends up in databases or content management systems, where it can be effeciently re-used for documents produced by multiple departments.

Technical writers are finding themsleves in the middle of this process. Why? Because our skills are often the closest fit for the job. We have the ability to make difficult content decisions and also to handle the technical details. Writers who continue to focus on content management technology will find themselves increasingly valued.

Multimedia development

Paper manuals have become relics of the past. End users are finding their information via search engines and social media. Also, they now expect to find more of that content in forms other than writing. Youtube and podcasting have trained them to look for video or audio explanations of how to complete tasks, and our authoring tools have adapted to allow for delivery of technical content in such formats.

Demo tools such as Camtasia and Captivate are becoming increasingly popular in the user assistance world. Often these tools are used to create full-blown tutorials with voice-overs. Technical writers will not only need to learn how to record demos effectively, but also how to integrate them into help and other delivery platforms.

Most help content now includes at least a few video tutorials or demos to show how tasks are completed. Technical writers should be learning how to create effective screencasts, and record high-quality audio voice overs. Chances are you'll be assigned to such projects in the future if you haven't already.

Behavior analysis

You can learn a lot about the needs of your end-users by monitoring their behavior. Usability studies can be very insightful. By watching how people interact with your documentation, you can find ways to improve it.

Technology can help. Some help authoring tools now offer the ability to track topic visitation, search data, and other behavioral data when documentation is stored on a server. By moving your content to a server and using server logs and other tools to analyze how it is being used, you can gather a great deal of information for improving your documents. Technical writers who are skilled at analyzing this data and knowing how to apply it for improving content will find themselves in greater demand.

XML and XSLT
Many of us are using DITA or DocBook already to create multiple deliverables from XML source content. However, authoring tools are adapting to these standards and WYSIWYG editors are available for XML content. The true benefit of learning XML and XSLT will be the ability to work "under the hood" on XML-based content. Also, now that many of our tools use XML as a native document format (such as Word documents, RoboHelp project files, etc.), writers who can work under the hood will be able to troubleshoot corruption issues, create custom translations for automatically generating documents in these formats, and more.

Search optimization
There is a gaping semantic void between how users think and how writers write. Even the most robust help system will be of little use if users cannot find the content they are looking for. The effectiveness of help can be drastically improved by researching what language users enter into the search field, and by mapping the help content to the existing understanding of users.

Server-based scripts
Help content is slowly migrating to the Internet. This allows help authors to implement functionality that isn't available for locally installed help. Scripting languages such as ASP, JSP, and AJAX will allow future help authors to take advantage of the server and create help that integrates more heavily with stored user data, web tools from other vendors, and more.

User generated content
As user forums and wikis become more robust, help authors will need to learn how to effectively integrate content from those sources into the help. Also, technical writers will need to clarify their role in working with user-generated content. Should writers participate in these discussions? How can user content be leveraged for filling in gaps in the help? Technical writers will need to help answer these questions to provide a more thorough and seamless experience for users.

These are just a few skills you can develop to improve your value as a technical writer.