How to convince others of the importance of documentation

If you've been a writer for long, chances are you've had to convince someone of the importance of documentation. It just comes with the territory. People often don't see the value of well-documented information. They don't get that documents can be a life or death matter.

So how do you convince them?

Here are a few tips for arguing the importance of documentation.

Refer to the bottom line

Writing technical manuals saves money. It reduces Support calls, decreases accidents, and improves each user's experience with the product. Your first tactic in convincing others of the importance of documentation, especially developers and business managers, should be to show them how it makes the company profitable.

Show how documentation makes the product more usable

When arguing with developers or engineers, point out how writing technical manuals helps more users take advantage of advanced product features. Educated users will be more effective at completing tasks. They'll also have a greater appreciation for the design of the product. Appeal to the engineer's ego. They'll see the importance of documentation if you show them how it makes users have a fuller appreciation of the product's usefulness.

Carry the burden

Often a developer, engineer, or manager isn't arguing so much about the importance of documents. Instead they simply don't have time to make it a priority. They are often bound to a product release cycle that doesn't include time for writing technical manuals.

Lighten their burden and you might find them more receptive to working with you on documentation. Offer to schedule an information gathering interview so that you can pick their brains in one session, and then use that time wisely. Ask smart questions. Then get to work writing the documentation and try not to be a pest.

Gather user feedback

A lack of user feedback can often lead to doubts about the importance of documentation.

Think about it. How often does a user tell you that they've had a successful experience with the help or manual? It's usually the other way around. You hear from users when they can't find the information they are looking for.

If you want to convince someone of the need for documentation, try implementing a feedback system in your help or asking the Customer Service or Support staff if they have any positive stories from users regarding the documentation.

Write something useful

Some people do not understand the value of documentation because they've had too many negative experiences with poorly written doc. These folks are tough to win over. You just have to buckle down and keep writing useful content, and over time they will gradually catch on to the value added by a good technical manual. Give them enough good experiences to make up for the bad.

Whenever you try to argue the value of documentation, remember to point out that a successful documentation experience is one that you probably will never hear about. Happy users are quiet users.

If you enjoyed this post, you might also like: Why software development documentation is essential.

How to write when you're tired

Technical writing is difficult enough when you are fully rested. When you're tired it can be downright tedious. How can you spot an outdated GUI reference, write a coherent procedure, or judge whether a help topic is indexed properly when you can hardly stay awake?

Here are a few tips to help you stay focused when you're feeling drowzy.

Save heavily conceptual work for another day - Some tasks, such as categorizing content, making decisions with far-reaching implications, and writing procedures from scratch require a lot of brain power. You simply have to be coherent to do these things. To make your technical writing job easier when you feel tired, flag these conceptual tasks as To Do items for another day.

Focus on simple and clearly defined tasks - Many technical writing tasks, such as spell-checking documents, validating HTML topics, and incorporating straight-forward comments from reviewers can be done on autopilot. Try to stick to such tasks when you are tired. That way you can feel productive without running the risk of making mistakes you'll regret later.

Watch what you consume - Eat a small lunch, and don't drink too much coffee. Carbohydrates and caffeine can cause serious fluctuations in your energy level.

Ask for a peer review - If you must do heavy duty technical writing when you're feeling drowzy, ask another technical writer to peer review your work. A second set of eyes can only make your documentation better.

Take frequent walks - Technical writing isn't exactly a high-impact sport. Get up and take a walk now and then to get your blood flowing and clear your head.

Put on your headphones - Most technical writing jobs require a quiet environment, but the silence can put you to sleep if you are already short on energy. Put on some headphones and blast an obnoxious tune now and then. Like rolling the windows down when driving for long periods, the music can jolt your brain back into an alert state for a precious few minutes.

Chat with a coworker - A good conversation now and then will help reset your brain to an alert state. It also helps you stay connected and in the loop. Chat about a project that you are working on, or just talk about your weekend. Either way, you'll be building positive relationships with your team.

Find a fun project - Some technical writing tasks are tedious by nature, but others can be a lot of fun. By focusing on the more exciting tasks and changing your routine, you'll find you are able to muster more energy and attention. Skip editing the copyright page of your manual until you are more alert. Instead, work on the tutorial you are developing using the latest multimedia tools.

Take some time off - Maybe your body is trying to tell you something. Technical writing is hard and stressful work, and it can really tax the brain and burn you out. Take a vacation and give your mind a rest. You'll feel much more alert after a week of soaking up the sun on a sandy beach.

Take a long lunch - If you can't take a vacation, just take a long lunch. Go to the golf course, take a bike ride, or go shopping. An extended lunch break will help get you through a long day.

If all else fails, just pay a coworker to stop by and give you a good shake now and then.

Related posts:

9 tips for writing better FAQs

Frequently asked questions, or FAQs, are an important part of your product documentation. Writing well-targeted and thorough FAQs allow users to quickly find the answers they need so they can be more productive when using your product. Here are some tips for writing FAQs that will get your users on track quickly and help reduce Customer Support calls.

Phrase your questions like a user - Users must recognize that an FAQ answers their particular question. The title of your FAQ should phrase the question in the same language a user would. Ask your Support department for feedback; they talk to users on a regular basis and can assist you with the words users choose when asking questions about the product.

Refer to existing procedures - When answering user questions, leverage your existing documentation. Your answers should point to procedures that guide users through the tasks they need to complete. By leveraging existing documentation, you avoid writing duplicate content and dealing with consistency issues later on.

Implement a feedback system - Use feedback forms in your help so that users can help you fine tune your content. This allows users to tell you if your answer glosses over an important detail, or if there are related questions that aren't covered by your FAQs.

Talk to Customer Support - You can fill in the holes in your FAQs by talking to members of you Customer Support team. They are on the phones with users regularly, and can tell you the kinds of questions users ask on a regular basis. Chat with them often and evaluate whether your FAQs need to change based on changes in the product or user behavior.

Group related FAQs - Organize your FAQs by subject matter, and use a topic list with subheadings to group them. This allows users to find particular questions quickly, and spot related questions that they didn't think to ask.

Include cross-references to related FAQs - Conclude each answer with a list of related questions. Users may not think to ask about important details that are related to the FAQ they are currently reading. By listing related FAQs, you put those issues on their radar and save them later trips to the documentation.

Restate the question in the answer - Begin each answer by rephrasing the question. That way users can clearly see that your answer is indeed going to provide them with the information they are looking for.

Index FAQs by subject - Be sure to index your FAQs. While readers will often access your FAQs from an FAQ list, you can also help users find this information by indexing it under the appropriate subject.

Refer to user-generated documents - Leverage your user community by including a reference or link from each FAQ to the knowledge base or user forum for your product. Often these user-generated resources are updated faster than your manuals and help. Also, by encouraging use of the forum or knowledge base, you gather more user feedback that can be used to flesh out your existing documentation.

Follow these tips for writing great FAQs, and your users will thank you.

You might also like:

Why write instructions that no one is going to read?

Ouch. That's a tough one. Is technical writing worth the effort? Hmm...

Ok technical writers, it's time for some motivation. Everyone take a deep breath, grab some comfort food, and follow my lead.

Now repeat after me.

"My work is useful."

Seriously. Technical writing is useful.

Now before you start to doubt, keep in mind that I'm aware of the situation. I know that no one knows how to program their microwave properly, sync their PDA, or use their on-board auto navigation system to its full potential. I'm aware that not a single person on the planet earth knew how to program their VCR from the time betamax was popular to the time digital video made VCRs obsolete.

I know that a lot of people never read instruction manuals or online help.

But you know what? Some people do.

For every mechanic that learns by trial and error, there's one with all of his fingers still attached who read the repair manual. Or one that disconnected the negative battery cable before digging under the hood as your manual advised. He's the one that didn't get burned. He's the one that understands the importance of documentation.

What about the accountant stuck in her office at 7p.m. who figures out why her calculations are off by reading your troubleshooting topics? Do you think she appreciates your work? How about her husband and kids who get to eat dinner with her because she made it home on time? To her technical writing matters.

And how about the kid on the playground who gets an extension on life because his mother read the instructions for using an epinephrine auto-injector? To that kid, technical writing matters.

Do I sound a bit dramatic? Good. Because for every room full of joe-schmoes who don't read the manual, there's one like I describe above.

That one user is the reason we get up each day. Forget everyone else and write for that user.

Do not underestimate the importance of documentation. The world needs you. And it needs technical writing.

-If you enjoyed this post, you might also like How to convince others of the importance of documentation.

How to become a technical writer

If you are interested in becoming a technical writer, these tips may help you get started. We'll cover a range of approaches for building your reputation as a professional. Also, we'll discuss what is involved in the day-to-day work of technical writers, and what skills you will need to be competitive.


Tip: If you're looking to get started right away, check out these online courses.

Step 1: Meet the education requirements - a degree in English, Journalism or Science

Most job descriptions ask for a bachelor's degree in English, Journalism, Science, or a related field. A lesser degree, such as an Associate's degree, might get you an interview for some positions. However, if competition is stiff, an advanced degree might be necessary to give you an edge above competitors.

Many universities now offer writing programs with a focus on technical or professional writing. Some of these courses will be managed by the university English department. You may also find technical writing courses in the Engineering program. Talk to an advisor or admissions officer if you have questions about what courses and degrees are available. You may find that the course content differs quite a bit depending on which department manages the course. For example, classes in the Engineering program may have more of a technical focus than those offered as part of an English program.

If you don't have a college degree, you may still be able to land a job as a technical writer. Any previous job experience that relates to technical writing should help. For example, if your previous jobs required a lot of writing or communications skills, employers may see that as a sign that you can handle the responsibilities of a technical writing job.

Many schools are now offering technical writing certification programs. These programs can usually be completed much more quickly than an actual degree, and might help you transition into the field. If you pursue this option, be sure that the certification program covers the core skills, tools, and other subject matter that you will need to work in an entry-level technical writing position. Certification might also give you an edge over other candidates if you already have a degree and some experience in the field, or if you are trying to build a freelance business.

Be sure to make the best of your education. Spend as much time as possible networking with fellow students who are entering the field, and with instructors that have business connections and professional contacts. The friends you make during college might provide valuable job contacts in the future; also, you can offer each other mutual support when you have career decisions to make or are struggling with difficult research questions.

Step 2: Decide what kind of job you want

Before you dive into applying for technical writing jobs, you may want to think a bit about which industry you prefer to work in. Writers are commonly hired in the medical, software, and engineering industries, as well as others. Think carefully about the kind of environment you'd like to work in, as well as the subject matter you wish to write about. I can't emphasize this enough; as a professional tech writer you'll be reading, writing, and editing a ton of content related to the products your company produces. Try to find subject matter that interests you.

You should also research the companies you want to work for; know their products and why you want to work for them in particular. Do they have a company culture that suits your personality? Are you familiar with the products they produce? The more research you do about a company before asking for a job, the better your chances will be at landing that job. Employers like to hire people who are passionate about helping the company achieve its goals.

Step 3: Learn the appropriate skills

To become a technical writer, you must first develop the skills necessary to complete documentation projects. In addition to a traditional education, you can also consider certification programs and training from software or tool vendors. Here is a list of the abilities you will need to develop.

  • Tool knowledge (in-depth word processing, HATT, HTML/XHTML, etc.)
  • Information gathering and working with subject matter experts
  • Project management (scheduling, deadlines, facilitating reviews, etc.)
  • Writing concisely
  • Editing and proofing
  • Publishing and delivery process (probably job-specific)
  • Research

Step 4: Understand the many types of technical writing projects

A career in technical writing will require you to work on many kinds of documentation projects, including the following:

  • Print documents (user manuals, white papers, quick-reference, installation guides, training guides, proposals, etc.)
  • Locally installed or server-side help topics
  • Community-based documentation (knowledgebase, wiki, forums, etc.)
  • Video demos / screencasts

Step 5: Learn what managers are looking for

As you look for a job, keep in mind the traits and skills that managers are seeking. Beyond basic competency as a technical writer, they want to know that you are capable of managing projects, meeting deadlines, and working without to much hand holding. If this is your first job in the field, don't worry. A good manager will help you get settled in and adapt to the department's workflow. Much of what you will need to know will be learned on the job. When you are just starting out, focus on learning the process for creating deliverables, learning company policies, and keeping your projects on track. The ultimate goal is to be able to work independently and get the job done.

Beyond project management, potential employers will want to see some ambition for your career. If you are excited about the field of technical writing, and about certain aspects of your job, you are more likely to perform well and become a key player on the team. Remember, your manager will need to get a sense of how your individual skills will contribute to the success of the department. Where do your strengths lie? Are you a strong researcher, writer, or editor? Are you good at tracking project status and getting things done? Perhaps you are great at resolving technical issues or enhancing the documentation process so that it is more efficient? If an employer can see these strengths, they can better assess how you will contribute to the team and whether you are a good fit for the job.

A potential employer may need to know whether you can adapt to the tools the department uses on a daily basis to produce documents. You don't usually need to be an expert in every tool on the market. Instead, focus on developing a bit of experience with one tool in each class. For example, if you have worked a bit in RoboHelp, chances are you'll be able to adapt to working in Flare or a similar help authoring tool. If you are familiar with FrameMaker or Word, you'll probably be able to adjust to working in a different page layout or word processing program. Don't feel that you need to be an expert right away; just show that you are able to learn and adapt.

You can gain some advantage by researching and experimenting with cutting edge tools that are shaping the field. For example, working with or learning about Content Management Systems or screencasting tools might give you an advantage. Many departments are working to build expertise with such tools, and knowing a bit about them might prove that you can help blaze that trail. Often you can find free or open source versions of these tools that allow you to practice and build your skills.

Step 6: Build a portfolio

A portfolio of professional work can help you demonstrate your skills to potential employers. Let's talk a bit about the kinds of work you should include.

Remember, the purpose of a portfolio is to demonstrate your knowledge. Past projects can show a potential employer whether you have solid writing skills, what your strengths and weaknesses are, whether you are able to gather information effectively, and how clearly you can present information to others.

Start by filling your portfolio with the most impressive examples you have from your past work. Be sure to contact your former employer if you are including examples of their documentation; you may need their permission to include such work in a portfolio that will be shared with other companies. Pick projects that show your ability to gather and write content (manuals written from scratch), manage a project (schedules or gantt charts), and publish content in a variety of formats. Also, include any projects that highlight your strengths. For example, if you developed a process for single-sourcing print and online content, include it in your portfolio.

If the project was a collaboration, highlight areas that are your work. That way employers don't confuse your work with that of your former co-workers.

If you don't have previous job experience, you can still build a professional portfolio; you'll just have to be creative. Find an open-source software application that doesn't have help content and write some. Learn how to use the program effectively and then document the process for others. You can also get in touch with the developers of such projects and offer to document their work; chances are they'll be happy that you offered. You may run into some territorial developers who don't appreciate the value of technical writing, or who think their own attempts at documentation are sufficient, but don't let this discourage you. Just move on to a different project.

Projects from your school coursework can also make great portfolio content. If your classes are well targeted to the field, chances are you will have some projects that demonstrate skills that are in demand. Any papers you've written about technical subjects are great material for your portfolio, and so are web-based projects such as help content or even personal websites. Just make sure the subject matter is appropriate and somewhat professional so that employers don't get distracted from evaluating your skills.

Your portfolio can take many formates. For example, printouts can be neatly arranged in a binder. Online projects can be posted to a personal website. You can also deliver your portfolio content as a DVD or CD. Just be sure that the format is convenient for interviewers to access, and that you follow any guidelines written into their instructions for applying for the job. Also, if your portfolio contains documents owned by a previous employer, be sure that you have permission to distribute them in the chosen format. For example, past employers may be more comfortable letting you show interviewers a binder of your work than allowing you to distribute a CD that the interviewer will keep indefinitely.

Step 7: Build your network in the industry and apply for openings

As many have said before, it's not what you know, it's who you know. Networking is a key factor to finding a job in any field. By expanding your social network you increase the chances of discovering career opportunities.

Several technical writing forums exist, including the techwr-l mail list, the HATT list (for help authoring tools), and more. By participating in these communities and contributing, you can increase your knowledge, get to know fellow technical writers, and build an extensive online profile that demonstrates your knowledge.

The Society for Technical Communication (STC) is also a great place to talk with others about becoming a technical writer. Don't just join and be passive; introduce yourself to other professionals in the field and attend meetings. You can even volunteer to help out. This is a great way for a new writer to get some experience and exposure.

You can also join related professional associations (software developers, etc.) to spread your net a bit wider. This is a great way to meet professionals with skills that compliment your own.

Step 8: Continue learning and developing your skills

The job description of a technical writer is constantly changing due to technology. If you keep up with these changes and adapt accordingly, you will gain an advantage over your competition.

Focus on learning cutting-edge skills. Experience with content management systems (CMS), single-sourcing, social media documentation, and other industry-chaping technologies will help you contribute value to a team of technical writers.

You can learn much about these tools and strategies from industry blogs, periodicals, user groups, and by downloading free trials of software.

How I became a technical writer

I'm dating myself here, but why not...

Once upon a time there was a computer company called Commodore. Back in the early 80's, when I was in the fourth grade and had accumulated an entire collection of Masters of the Universe action figures, they released a computer called the Commodore 64. It was awesome. It used floppy disks the size of textbooks and made crunching noises when the drives couldn't find what they were looking for. (It also booted instantly to a command prompt; no waiting for things to load.) And it ran the best video games I'd ever seen, in full color and with awesome sound.

One day I played Archon on a C64 at my dad's friend's house and was blown away. I had to get one.

I can still remember standing in the computer store three days before Christmas helping my dad fill a box with all the components we'd need. (No monitor; it just plugged into the TV.)

When I got the thing home I started reading the manual. No kidding. (Back then home computers were just a hobby; therefore, it was assumed that if you bought one, you planned on learning how to program it.) The C64 manual had the most incredible tutorial on BASIC programming I've ever seen. It still stands up as a great example of technical writing. I learned about pixels, drive sectors, arrays, and all kinds of stuff I never thought I'd use again. It really made me appreciate the importance of documentation.

I had a friend that read the same science fiction books I did and his dad ran a computer business out of his basement. We'd spend days writing sci-fi word games on his dad's computers and learning how to write code. And when we were burnt out on computers, we'd play baseball and swap books.

As I grew older, the usual distractions (dating, trying to stay out of trouble, and a Kramer electric guitar that I still own) scattered my attention.

By time I entered college I had no idea what I wanted to do with the rest of my life. I picked a major in English Literature because I liked to read books. After I earned a BA in Literature, my advisor pointed me to a Masters Degree program in Professional and Technical Writing. I knew my chances of becoming a beat poet or rock star were slim, so I jumped on the opportunity.

My experience as a graduate student enlightened me to the fact that I actually had some marketable computer and writing skills. Through perseverance my professors managed to pound some very useful theory into my head, and they involved me in some school projects that helped hone those skills. I also learned to further appreciate the importance of documentation, and that technical writing could be a decent and enjoyable way to make a living.

Then, one fateful day, my technical writing professor told me about a job opportunity that sounded promising. My wife and I were just married. College was expensive. So I took the plunge and entered the 9-5 world. I became a professional Technical Writer.

That was nearly a decade ago, and I haven't looked back since.

When I started college I had never heard of technical writing. Now, I can't imagine myself in any other career. I just sort of fell into it through my love of books and computers, and the guidance of some great teachers. And the rest is history.

So that's my story. That's one way of becoming a highly-paid technical writer.

See also: Technical writing career advice from 11 experts.

10 brilliant help ideas from Microsoft Office 2007

If you're looking for some new user assistance tricks to enhance your product, you might want to take a close look at the Microsoft Office 2007 help. The technical writers and developers at Microsoft have put together a help system that is incredibly user-friendly and accessible. (Why can't I be as smart as those guys?) Here are just a few of the help features that caught my eye.

Instant search - When you launch the help, the cursor immediately appears in the Search field. This allows users to find the information they need using their own words. This is a stark contrast to three-pane layouts that default to showing an index or table of contents. While such navigation features offer strengths of their own, they require users to map their thoughts to the terms that technical writers have hard-coded into the navigation. The Search feature lets the computer handle such conceptual mapping.

Browse list - Under the Search field is nicely-organized menu of help topics for users who prefer not to use Search. This menu is sparse and high-level, and can be scanned quickly. Although it takes some clicking and guessing to dig down to specific information, the menu does a nice job of complimenting the Search without overwhelming users.

Topic icons - Microsoft uses icons for different types of help topics. When a list of available help topics appears, the icon next to the topic tells users whether the topic is part of the locally-installed help, or whether it accesses information on a server. This is great for users who aren't connected 24/7, or those who don't want to wait for information to download.

Look and feel - The help has a light, airy feel to it. Even dense procedures seem welcoming and easy on the eyes. At times the color of headings and text is a bit too light, and might be hard to read for those with poor eyesight. But overall, the use of white space and lighter colors is soothing and makes reading the help a much more enjoyable process.

Breadcrumbs - Office 2007 help offers a great example of how to use breadcrumbs effectively. Whether you reach a topic via browsing or from the Search field, the breadcrumb navigation gives a strong sense of where you are in the help. I often find myself clicking the last link in the breadcrumb path to go up a level to conceptually related help topics.

Demo labels - Topic titles for software demos are clearly labeled. The word "Demo:" precedes the title of each. This makes it very easy to find the demos when browsing the help, and see that you are about to download something when you click the link to the demo topics.

Screenshots - Office 2007 help has some of the most attractive and useful screenshots I've ever seen. Many are cropped with fancy Bezier curves and sport drop shadows. While you might think such things would distract readers, they are actually quite appealing and add to the pleasant look and feel of the help. Also, most of the screenshots have very useful captions, and are effectively used for illustrating concepts in the help. I can't imagine how much time the technical writing staff put into these shots. Well done.

"In this article" links - Many lengthier help topics in the Office 2007 help are preceded by "In this article" menus that link to subsections of those topics. These menus serve as useful tables of contents for seeing what material each topic covers, and accessing that content quickly.

User-friendly feedback form - The server-based feedback form at the bottom of most help topics is both elegant and unobtrusive. The form itself only appears after you click one of the "Was this information helpful" buttons, so it doesn't distract your attention from the content. Also, the form is smart enough to realize which button you've clicked, and asks you for appropriate feedback based on your choice.

Tags - Office 2007 help topics often contain a list of tags. These tags are used to group similar content that is available via Microsoft Online. The help topic "What are tags?" implies that the tags are generated by other people, but I'm not sure if this means other Office 2007 users, or technical writers at Microsoft. (Does anyone happen to know the answer to this one? If so, please share by leaving a comment.) If the tags are user-generated, I have to give Microsoft kudos for adding them to the help.

Again, this list just scratches the surface. The help for Office has improved vastly over previous releases, and I was really impressed by the way help was implemented. So if you want to learn a few tricks for your technical writing bag, spend a little time in Office 2007 and grab a few ideas from the smart folks at Redmond.

Similar posts:

11 tips for writing incredibly useful procedures

Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.

Fill in the holes - Ask yourself if your existing procedures cover all of the tasks users need to complete. You may be missing a few, especially if features have been added to your product. If you have a set of well written FAQs (and you should!), make sure there are procedures for addressing the details of each FAQ.

State the goal - Unless it is already obvious, begin by telling users the reason for performing the procedure, and in what conditions it is applicable.

Break it down - Lengthy procedures are harder to follow. Break these behemoths down into smaller chunks and use hyperlinks to guide users from one granular task to the next. Aim for 10 steps or less in each procedure.

Don't assume - Read carefully through your procedures and ask, "Is there anything a user would need to know that I've left out?" Don't assume that users know everything you know about the product. Technical writing is all about acting as a user advocate.

Use warnings - For each step in your procedures, carefully consider whether there are any potential risks or dangers that you haven't documented. A good technical writer will put user safety first.

Link related procedures - Whenever possible, especially in help, use cross-references to point users to related procedures. Most users need to perform multiple related tasks in order to complete their goals. For example, a procedure about using the Print Preview function in your software should be linked to procedures for the Print function.

Tell users what to expect - Consider whether the results of each step need to be documented. Good candidates are those that result in changes in the state of the product (e.g. an important prompt appears in the software, or the blades on the lawnmower begin to turn). Your description of the result should immediately follow the instructions for that step.

Watch for branches - Often a step in a procedure can have multiple results. If your procedure branches, consider making each branch a separate procedure. Use links or cross-references to guide users through.

Combine small steps - Usually it is best to write only one instruction per numbered step. However, small steps can often be combined. For example, "Click the save button" and "Close the application" can be combined into "Click the save button and close the application." Combine multiple small steps only when the concepts are simple enough for users to think of them as one.

Give users an overview - Use a flowchart, list of links, or other visual cue to help users see how procedures are related. This will provide users with an overview to guide them through a complex series of tasks.

Follow up with results - At the end of the procedure, clearly describe the results so that users can assess whether they were successful in completing the task. The more complicated the task, the more assurance users will need. Good technical writing should leave users feeling comfortable about their experience with the product.

For specific guidelines on writing policy and procedure manuals, see

Resource: How to Write Policies, Procedures & Task Outlines

Similar posts:

Which XML editor should I use?

Choosing an XML editor can be a tedious process. As with most technical writing authoring tools, you need to find one that fits your specific documentation needs.

First, make a list of your requirements. Do you need a tool with user-friendly features and extensive help that will allow for an easy transition? Or are you looking for a slim and trim XML editor for some serious hand-coding? Perhaps you need a full-blown content management system, or a tool that supports a specific schema or DTD?

The good news is that you have plenty of options. Whether you're looking for a proprietary tool with an extended customer support plan, or an open-source editor that will help your budget, you should be able to find an XML editor that meets your needs.

Here is a rundown on some of the more popular XML editors.


Cost: $695 - $1395 depending on version

Strengths: Full DITA support, Documentum integration, collaborative editing, user-friendly WYSIWYG interface, extensive language support, simple publishing to various output formats.


Cost: $225

Strengths: WYSIWYG editor, DocBook and DITA support, Eclipse IDE support (for Java users), support for multiple XSLT processors, query support for XML and relational databases.


Cost: Free

Strengths: Great bare-bones XML editor (no WYSIWYG), small download size, customizable library of snippets, works with most XSLT engines.

Altova XMLSpy

Cost: $499 - $999 depending on version

Strengths: Graphical schema designer, database integration, plugins for Visual Studio .NET and Eclipse, support for Office Open XML documents, editor with multiple viewing options.

Open Office

Cost: Free

Strengths: Office suite and XML editing in one package, extensive user community, familiar word-processing environment. (Note that Open Office documents can be saved as XML, but does not handle translation or other tasks. You'll need to either create your own translation process or invest in one of the other more robust editors mentioned here.)

Arbortext Editor

Cost: Call Sales (likely differs quite a bit depending on whether you want the full-blown CMS)

Strengths: CMS integration, content reuse, translation, dynamic content, familiar word processing interface, support for DITA and other standards, highly configurable.

A free trial version is available for most of these. Download those that you think might meet your requirements and give them a test drive. With DITA and single-sourcing on the horizon, an XML editor may quickly become one of your primary technical writing authoring tools.

Good luck!