Thursday, February 21, 2013 #

Topics on Steroids

Ektron product documentation puts a new twist on topic-based information, creating a streamlined, single-sourced, multi-formatted, topic-based information delivery system.

Traditional topic-based documentation links discrete chunks in a chain of related-but-often-isolated, granular bits. Ektron groups the discrete relations into parent topics. The output is compressed in accordion fashion using the drop-down feature that is available in the MadCap Flare authoring tool. Some parent topics are as large as 50 PDF pages (and more) containing dozens of children topics but are displayed in a single help topic while providing the reader with easy access to all related information. 

The accordion method improves the user experience by letting readers scan and access discrete topics on one help screen, without losing context by jumping from topic to topic. Drop-downs optimize information so that differently skilled users can scan essential information, and open the information they need more quickly. For example, Ektron hides images, code examples, field descriptions, and other information that can slow down an expert user. Each user at every skill level gets the right amount of information, easily expanding on it with a click when more is needed or wanted.

A by-product of taking this approach resulted in a huge savings in content file maintenance. Instead of managing many hundreds of small, discrete topic files, we merged files into parent topics, thereby reducing the number of content source files we needed to manage by a staggering 60% or more.

That is not all! The accordion approach made our mobile format easy to navigate and "finger-friendly." (We also placed QR codes in the Web and PDF formats to make it easy for customers to scan and get the mobile-formatted documents on their hand-held smart devices.)

The Ektron Reference covers over 2100 (PDF) pages of information. We optimized source content for online and mobile consumption (by converting many tables to lists, for example) and that also has resulted in an even bigger savings in the PDF page count. Using conditions, we use a single-sourced project to generate Web (HTML5), and PDF documents for multiple releases. 

I'd love for you to have a look for yourself at the Ektron Product Documentation Page.

Ektron Reference - Web (HTML5)

Mark Metcalfe

Posted On Thursday, February 21, 2013 9:58 AM | Comments (0)

Friday, February 15, 2013 #

Accurate and Complete are not Enough

Suppose that you asked me to help you write a blog. How would you feel if I handed you the unabridged Oxford English Dictionary and told you that "it has every word you will ever need for your blog. It is the most accurate and complete tome you can find!" While technically true (being accurate and complete), the dictionary is not useful for telling you how to arrange the words to make you a competent blogger.

We rightfully stress accuracy and completeness when we describe doodads, widgets, and thingamabobs in technical documentation. However, it is more important to emphasize making documentation useful. 

Useful documentation starts with understanding the intended purpose of the software (or other object), answering the "why" and "how" questions, such as:
  • "Why would I want to (or need to) fill out the fields in this dialog box?"
  • "Why is it important to follow the procedure?" 
  • "How have other people used the product to good effect?" (What are the best practices?)
Answering such questions goes a long way toward developing competency in a user, making information useful, but even that is not enough. If information is difficult to find, your great documentation may be like the proverbial tree falling in the woods with no one to hear it make a sound. You also have to make the information easy to find.

Creating a user experience that is useful depends a lot on your audience. Some customers may need a printed document* with a well-formed table of contents and index; others need to open progressive levels of information using finger-friendly-formatted documentation for mobile devices. In many cases, useful documentation makes information easy to find by providing multiple means of access (such as TOC, index, topic list, and search) that is (intuitively) easy to navigate.

When you put it all together, useful documentation transfers competency knowledge through accurate and complete information that is easy to access and navigate.

Mark Metcalfe

* I worked for a hardware company that needed paper documents in the field. A slick Web help system or video tutorial were not useful forms of information transfer for that user base. Know your audience.

Posted On Friday, February 15, 2013 4:20 PM | Comments (0)

Thursday, November 15, 2012 #

Companies and Ships

I have worked for small, medium, large, and extra large companies and they have something in common with ships. These metaphors have been used before, I know, but I will have a go at them.

The small company is like a speed boat, exciting and fast, and can turn on a dime, literally. Captain and crew share a lot of the work. A speed boat has a short range and needs to refuel a lot. It has difficulty getting through bad weather. (Small companies often live quarter to quarter. By the way, if a larger company is living quarter to quarter, it is taking on water.)

The medium company is is like a battleship. It can maneuver, has a longer range, and the crew is focused on its mission. Its main concern are the other battleships trying to blow it out of the water, but it can respond quickly. Bad weather can jostle it, but it can get through most storms.

The large company is like an aircraft carrier; a floating city. It is well-provisioned and can carry a specialized load for a very long range. Because of its size and complexity, it has to be well-organized to be effective and most of its functions are specialized (with little to no functional cross-over). There are many divisions and layers between Captain and crew. It is not very maneuverable; it has to set its course well in advance and have a plan of action.

The extra large company is like a cruise liner. It also has to be well-organized and changes in direction are often slow. Some of the people are hard at work behind the scenes to run the ship; others can be along for the ride. They sail the same routes over and over again (often happily) with the occasional cosmetic face-lift to the ship and entertainment. It should stay in warm, friendly waters and avoid risky speed through fields of ice bergs.

I have enjoyed my career on the various Ships of Technical Writing, but I get the most of my juice from the battleship where I am closer to the campaign and my contributions have the greater impact on success.

Mark Metcalfe

Posted On Thursday, November 15, 2012 11:06 AM | Comments (0)

Tuesday, September 14, 2010 #

My Writing Methodology

I was asked about the method I use for documenting products, so I thought I'd blog about it.

Topic-based information is essential to today's computer user, whether using web software or shopping online. Most users use information to get "unstuck." Learning methodologies or reading the Great American Novel are for the student or the insomniac. Most experienced users can figure out how to use more intuitive software but hit the occasional snag in a process. Only then do they turn to the information set, Googling for an answer.

So how does this inform today's documentation efforts? The Darwin Information Typing Architecture (DITA) is based on three main types of information: Concept, Task, and Reference.

  • Concept - Why do I want to use this piece of software?
  • Task - How do I use this piece of software?
  • Reference - What does this software do?

When I begin a project, I often start with the reference material because most of the initial users of a new release are more experienced and established customers. They know their way around and need only to refer to the help to jog their memory about a switch on a command, or an unfamiliar parameter on a dialog box. If nothing else can be ready at release time (for whatever reason), make sure that the reference material is in place for the early adopters of the release.

The next thing I tackle are the tasks, because nominal users need sequential steps to accomplish something with the software. These tasks must be short and discrete topics, not long tutorials to teach (although tutorials have their place in technical documentation).

The last thing to be written are the introductions, summaries, and overviews (concepts) because this information is better understood after the reference and task material has been tested and documented. Using marketing collateral is helpful at this stage to present a company message of how the software is intended to be used.

My primary focus with documentation is for online use with ancillary builds of a manual. Topics can be strung together to form a book (printable PDF, usually) but that is my secondary focus. The primary focus of documenting topics is to give a user only the information he or she is looking for with references to related topics, if they want further information. Get them in, get them out, and get them on with their jobs.

One of the newer additions to this model is the ability to hide screen images in drop down text so experienced users can skim through a procedure quickly while nominal users can open a link to see what the screen should look like. (These are called "comfort images;" to see that what is on the screen is what is described in the help.) I can add as many comfort images to online topics as I like because the images are seen only when the user decides. However, I still have to decide which images get conditionalized to show up in the PDF book version, where I need to be more judicious of the images I supply.

Those are the basics. There is a lot more to creating useful documents.

Mark Metcalfe

Posted On Tuesday, September 14, 2010 4:36 PM | Comments (1)

Monday, July 27, 2009 #

The Evolutionary Role of the Tech Writer

The one thing that has remained constant for a writer is the role of providing information content. However, providing a context for information is changing, again and again. Technological advances and consumer demands have created an explosion of contexts in which content can be consumed; and they want it all.

The high-level contexts for information content can be described as follows:

  • Content - Consumable (raw) data
  • Delivery - Presentation of data
  • Availability - Completeness of data
  • Accessibility - Navigating large collections of data
  • Structural coherence - Understanding large collections of data

Finer granularity of these contexts include such things as book-like information, GUI help, packaged software demonstrations (online quick tours, primers, tutorials, and animations), online seminars, FAQs, special interest communities, and more; (the list is hardly exhaustive).

The exponential scope and scale of the present-day Internet-enabled challenges will require several evolutionary paths for writers, each addressing the issues of providing processed information in a useful manner. I see at least three roles evolving for writers in an Internet-enabled world:

  • Content developers
  • Information miners
  • Infrastructure architects

A content developer is a writer whose task it is to document the use and function of a product or process. These writers have contacts closest to the development of a product. This role most closely identifies with today’s technical writer. The evolutionary path from writer to content developer is relatively smooth for any writer who has already experienced using a new tool or process to deliver content.

An information miner fulfills a purpose of finding information that is related to the use and function of a product or process. These writers are once-removed from the development aspects of the product, and closer to customer feedback forums, such as customer support databases and special interest communities. These writers gather related information and repackage both the content and context for better consumption.

An infrastructure architect focuses mainly on the contexts in which information is presented, ensuring that consumers are able to understand and navigate large virtual collections of data with relative ease. These writers have to possess knowledge to design a scalable infrastructure and to document the infrastructure (with meta-information). (A good analogy might be that these people are like architects of a city, planning major civic centers and roads that provide sufficient flow access to efficiently get from one part of the city to another.)

The following specific elements make up a world-class strategy for content development:

  • Information types are consistently presented in appropriate locations.
  • Expectations of how and where to find different types of information are consistent and easily learned.
  • “Help” anticipates a consumer’s need or desire, based on prior interactions or natural language queries. (Sometimes referred to as active help.)
  • Embedded help for all software products. (More traditional online help offerings)
  • A browser-independent interactive information system for each product.
  • Internet-based interactive (not passive) tutorials that are tightly integrated with software products.
  • Frequent and timely product information updates supplied to consumers over the web.

There are many organizational “owners” of information, such as Customer Support providing data for FAQs, or Technical Marketing providing Internet seminars (webinars) on new product features. All information needs to be channeled into a collaborative web-based architecture to make information useful.

Mark Metcalfe

Posted On Monday, July 27, 2009 3:59 PM | Comments (0)

Wednesday, July 15, 2009 #

Documentation is YOUR Business

Your technical writer has completed a 20-page draft of a feature that your team has been working on and sends the team a notice for review, allowing for a week to review it and make comments. You put it on a pile somewhere with a vague intention to skim through it before the next project team meeting. When the meeting arrives, you approve the documentation by your silence, relying on the expertise of the writer because the document never left your growing Inbox.

This is not uncommon. Reviews of documentation are very hard to come by, and when they do come, they are usually done by a very few conscientious persons; usually the primary developer and a technical editor (if your company is lucky enough to still employ them). Documentation reviews often are missed by people with specialized perspectives such as people in customer support, pre-sales, training, and quality assurance. As a writer, I know all the reasons and excuses (and some of them very legitimate), and I have accommodated many reviewers by extending review deadlines (often with meager results).

Aside: I will observe here that there is an inverse ratio of the cost of the software product and how accurate and complete the documentation needs to be at release time. If you sell a product inexpensively, then your razor-thin profit margins cannot afford the expenses of customer calls or inadequate documentation. Conversely, if you sell a very high-end product, you can send a product expert to hold the hand of the bleeding-edge customer who is willing to pay for the advanced versions of the software (while the documentation department continues to create content in preparation for the mass adopters of the product).

It is usually true that the more experienced writer on a project can mean that you can risk not reviewing the documentation – but in these economically difficult times, companies are more likely looking at costs rather than value, which means looking for lower cost alternatives - so weigh your risks before ignoring that review. Getting it right the first time saves money in the long run.

If the Ghost of Past Reviews visits you in the middle of the night, telling you that every customer call against faulty documentation is a new link in a ponderous chain, and you’ve said to yourself that the documentation is the business of the technical writer, permit me to shriek and moan and rattle some chains to remark that “Documentation is YOUR Business!” In the same way that the technical writer reviews and comments on software - offering usability suggestions to make the software better - other cross-functional members of the team have a stake in the documentation because it affects the perception about the quality of the product. Every member of the team is responsible for the output of every other member of the team, or all you have is a collection of talented but disconnected individuals.

Mark Metcalfe

Posted On Wednesday, July 15, 2009 9:52 AM | Comments (0)

Monday, July 6, 2009 #

Converting Legacy Info to Topics

Topic-based information is the way to convey information because answers to issues need to be concise, portable, and relevant. The trouble is that many companies have a lot of information already stored in old documentation formats. User guides are becoming rare; and they should, because the effort and cost involved in creating a user guide is too great compared to the number of users who need comprehensive information. Quick Start guides are replacing user guides and the comprehensive information is being moved into smaller chunks of information.

It is an easier job to create a DITA-based, XML-powered topical information system from scratch than it is to retrofit existing documentation into a new model. However, if your company is contemplating such a move, there are several phases you need to consider before making the switch.

Phase 1: Make sure your content is well-typed, meaning that the manuals are updated to have a consistent, standardized organization. Make sure that your sections can standalone as discrete topics, and can be typed as concept, task, or reference, (or some derivative of these types). Doing this will improve the usefulness of the documentation, even if you never convert the document into XML.

Phase 2: Choose the XML solution that works best for your situation and roll out the changes. Remember that customers do not care about the source of the information; they only care about the output, so a company should consider the costs of conversion, the longevity of the tools you will use (will the solution grow with you?), and the ease of use so that people outside of technical publications can contribute content in some way.

If Phase 1 is done properly, and the documentation is laid out consistently, automation can convert much of the content. If it must be done manually, a well-formed document will take much less time to convert, so spending time on Phase 1 is very important.

After the content is properly tagged, then it becomes a matter of how the content is distributed and displayed, which can take several forms (for example, HTML help, PDF, mobile help). This should be determined and developed while writers are engaged in Phase 1 activity.

Mark Metcalfe

Posted On Monday, July 6, 2009 9:09 AM | Comments (0)

Friday, June 26, 2009 #


To make a pun about an “elephant in the room,” one cannot discuss technical writing these days without involving India. It is a particularly touchy subject, especially for American writers, but I will hazard a few observations.

The quality of writing coming from India in the early days showed that it was in its early stages of development. Although, English-language-speaking Indians created a market for technical writers, much of the written content contained somewhat stilted language that a good technical editor could smooth out. When companies first started hiring technical writers in India, it cost a company between 20-25% of the cost of a writer in the US. The last I heard, the ratio was about 33-50% and that is applying pressures on companies to look elsewhere. This is particularly true of other job functions where use of the English language is not as critical (such as engineering and QA), and India is now feeling the pressure of less expensive costs elsewhere (China, Russia, and other Asian countries). China does not yet have a pool of English-ready writers, but English is being taught in grade school and it is only a matter of time for a technical writing market to open up in China. But I want this blog entry to focus on India because I can speak from experience.

In the early days, most projects that were assigned to Indian writers were mature projects that needed documentation maintenance; cutting-edge and new writing projects were trusted to the more experience writers in US-based offices. However, as the technical writing industry in India has matured, companies have found the economic savings involved too difficult to ignore.

So what is happening to the technical writing profession in the US? The good news is that it is not disappearing, but the bad news is obvious: there are fewer and fewer technical writing jobs available in the US with downward pressure on salaries.

What I hope American corporations will begin to recognize is that globalization need not equate to off-shoring, and that off-shoring is not the best way to create value. While it does cost more to have a distributed global workforce, there are definite benefits and value from having culturally diverse and geographically local employees.

When I became director of a global staff of writers, I obtained funding to bring the writing team together for a summit. I understand that sometimes these meetings are considered boondoggles, but not this one. There was a palpable change between the "before" and "after" dynamics of the team. Before, I had several centers of writing activity; after, we had a cohesive organization that collaborated on matters that concerned our craft and business. The writers from India were apprehensive about meeting their American counterparts, knowing that corporate economies applied pressure in their favor because of their lower cost structure. Coming eyeball-to-eyeball helped each to recognize colleagues - in a personal way - as talented professionals and not disconnected persons halfway around the world.

I have developed close friendships with several of my colleagues from India who are highly motivated and talented folks, earning a living at what they love to do – and I love working with them!

A global company needs a culturally diverse workforce to more effectively respond to the needs of their local customers. Further, the “cross-pollination” of culture and talent creates and broadens value that is greater than the sum of its individual parts.

Mark Metcalfe

Posted On Friday, June 26, 2009 1:09 PM | Comments (0)

Wednesday, June 24, 2009 #

Another Project

When I left Wang Laboratories and joined Digital Equipment Corporation (DEC to the DECCIES), I was hired to write about how to define tags in the Standard Digital Markup Language (SDML), a proprietary version for developing DEC documentation. My background in programming languages made me a good fit for the job. After I had ramped up on the project for several weeks, I called my supervisor one day and asked him if I could have another project. He immediately scheduled a meeting between us in a conference room.

In a serious tone, he said to me, "Um, Mark, we usually finish a project around here before asking for another project." I laughed and said, "No, no, you misunderstood! I meant that I was looking for an additional project." I felt that I could handle more than what put on my plate (and during the heyday of DEC, I could). I had volunteered to do more.

I did not get a new project right away, but it was not long before I was tapped for projects that needed urgent attention. Tackling hot projects is sometimes called "fire fighting" and I was developing a reputation for it. I built a good track record of it and carried this reputation throughout my writing career.

Mark Metcalfe

Posted On Wednesday, June 24, 2009 2:58 PM | Comments (0)

Tuesday, June 23, 2009 #

CORE Values

Some years ago, I developed an acrostic to help guide me as a Technical Publications manager. They have become my CORE values, standing for Clarity, Opportunity, Relevance, and Essentials. These concepts cover many of the issues any worker or manager deals with on a day-to-day basis.


Eighty percent of job anxiety is caused by not being sure what to do. Getting or providing clarity is a large part of getting things done. When things are unclear, productivity suffers. When things are clear, then you can make adjustments if things are not quite right. Having the objective in mind enables a person to start on the journey and make adjustments along the way.

As a writer, I sought clarity in my assignment and an understanding of how customers intended to use the product (and not necessarily how the engineer intended it to be used).

As a manager, I talked through assignments with writers until I knew they understood what the success parameters were. The more experience a writer had, the less we needed to talk through it, but clarity was very important to ensure that the project objectives were understood.


Opportunity is often an intersection between being prepared and recognizing a need. Clear objectives open possibilities of new or better solutions, and a good writer looks for ways to convey information in new and better ways.

There is a time element to opportunity, too. Opportunity needs to be seized while it is available.


Relevance is perhaps the most important theme because it defines the difference between best and optimum. The "best" may have a cost-prohibitive price tag associated with it, whereas "optimum" engages the law of diminishing returns to find the best return on the investment of time, energy, and resources. For example, a person can be the best chef in the world and take more than an hour to provide a sumptuous meal, but if a person at a sporting event is looking for a quick hot dog, the chef is wasting time making a soufflé. Similarly, you wouldn’t want a hot dog vendor barking at a fancy restaurant.

Knowing what the customer wants, needs, and can afford are critical to being successful. As it regards technical writing in particular, I have experience with projects that required very minimal documentation and was delivered outside of the corporate standard for documentation; it was a targeted need (a special order) by an important customer and time was critical. On the other side of the spectrum, I have experience with a comprehensive information set that must be carefully scrutinized before it is released. This is where company mission and vision statements are useful because they center an employee on activity that is relevant to the business.


Truthfully, I have often considered Excellence to be the final theme in my CORE values because I strive for excellence in my work. However, Essentials reminds me that first things should always come first. I had a writer on my team who was always thinking of new ideas. I put him in charge of an important initiative for multimedia in technical documentation. I knew he was up to the task but reminded him that if he failed to deliver on his assigned project, his work on the initiative would count for very little; our customers needed his documentation. (He did a great job with both!)

In the day-to-day decisions that have to be made, I think about these themes. Do we have clarity? What are the opportunities? How relevant is it to the objective? Are first things first?

So far, so good!

Mark Metcalfe

Posted On Tuesday, June 23, 2009 10:47 AM | Comments (0)

Monday, June 22, 2009 #

Tech Writers Need to Learn to Say Yes

As more deliverables were added to the work load of technical writers, I started to hear some of the other writing managers say that we needed to learn how to say “No” to additional work that simply could not be supported by the existing staff. I disagreed, offering what I think is a better approach to the very real problem of understaffing. I came up with an acrostic “SCAN” to communicate a better way to deal with a growing workload and still meet the demands of the business.

Say “Yes.”

When approached by upper management with additional work, recognize that managers have identified a way to further the business. Saying “yes” recognizes that we are partners in ensuring business success.

Communicate the Costs.

Saying “yes” is not free if you have scarce resources; something often has to give and managers should understand this. “Yes, we can do this, but it will take two weeks of attention and Project X may have to be delayed. There may be other options; let's discuss them.”

Ask about the priorities.

Return the power of decision to the decision-maker. “Is it more important to postpone Project X so that Project Y can be done in the time frame the company needs? If both are equal priorities, can we get additional resources to accomplish our goals?”

Negotiate the workload.

After you have partnered with colleagues and let them know what it would cost to assent to the new business requirement, help them to understand and come to agreement on the shifted priorities. “A delay of two weeks on Project X is acceptable so that we can accomplish Project Y now.”

“No” should be rarely used (if ever) in successful business. It stops the conversation and sets up a battle. “Yes” is the beginning of the conversation by collaborating with colleagues on a company priority while also dealing with scarce resources. If you are really "on the same team" then "Yes" is the only real way to make things happen.

Mark Metcalfe

Posted On Monday, June 22, 2009 3:12 PM | Comments (0)

Saturday, June 20, 2009 #

How I Got Started in Technical Writing

It's Saturday, so I feel like writing about how I got started in technical writing.

I took a computer class in high school and really liked it. I then took all the computer classes in college that I could. I was a business major at the time, but the computer classes were more appealing to me. When the school created a bachelor's program for computer science, I jumped in.

I became one of the computer lab assistants, and my professor noticed that I also had a knack for describing how to do things. He asked me to put together a document to help freshman get started with their own computer accounts, and performing the necessary tasks to use the computer. I was happy to do so, and they used the document for quite a few semesters. (This was at a transitional period for technology when some students were still bringing Smith Corona typewriters to college to do their papers.)

I wrote about using a text editor to write college papers, and students began to submit dot matrix papers. At the time, some of the professors did not approve of the perforated paper and strange font. Also at the time, my dad was a pastor at the college and he had been developing his sermons on the typewriter, too. I got an account for him on the school computer and introduced him to the ability to move an entire paragraph from one part of the body to another, and the backspace/delete keys. These were great innovations that some believed actually hurt compositional writing because it was too easy to amend one's writing on the fly.

I was one of the first three people at Eastern Nazarene College to obtain a bachelor's degree in computer science. I had little idea of the number of functional areas available to me in the computer industry. I thought I had to program code somewhere. (I was pretty good at COBOL and Pascal.) I landed four interviews out of college: two were for writing code, one for corporate training, and one for technical writing at Wang Laboratories in Lowell, Massachusetts. Thanks to my professor who saw potential in my helping abilities, I wanted to get into the technical writing field.

I was hired at Wang and really enjoyed my work. I still remember my first assignment, which was a 20-page document about a utility. I also remember the engineer's name with whom I met to gather information. I liked my job because I could play with computer software, point out the bugs (and not have to fix them), advise on how to make a program more intuitive, and write about it to help others use it. In many ways, I looked at my writing craft as programming in the English language.

My computer science degree helped me to quickly understand the more technically challenging products with ease and translate engineer-ese into common parlance for the user audience. It also helped me to develop macros for my colleagues and me to use to insert screen shots (back then, little more than a large text box) and to develop editing shortcuts.

I really appreciate my start in technical writing at Wang and still have friends from that time to this day. It has been a great career.

Mark Metcalfe

Posted On Saturday, June 20, 2009 2:33 PM | Comments (0)

Friday, June 19, 2009 #

Intelligent Design

"Don't go around the block in Boston," my dad advised. He gave me this sage advice long ago because the streets in Boston are not laid out logically. Boston is an old city that grew organically. In fact, many of the winding roads in Massachusetts are paved-over cow paths of old.

Think instead of Manhattan. If you are on West 42nd street, you can easily figure out how to get to East 23rd Street. That is because the streets are laid out in a logical progression and you can expect that 41st Street precedes 42nd Street and that the next street will be 43rd Street.

Along the lines of expectations, think about what you expect when you walk into a McDonalds or Burger King. You know that you can go almost anywhere in the world and get the same experience. (McDonalds in India serves chicken sandwiches; no hamburgers.)

When a company has an ocean of information, the key concepts to getting the information you need are access and navigation. If information is laid out consistently, on a web site or in the documentation set, customers can navigate easily through the system. For example, it means that Overview sections have the same kind of information and always appear in the same place. The regimentation gives users the confidence of knowing where to find the information they want to find.

Mark Metcalfe

Posted On Friday, June 19, 2009 12:53 PM | Comments (0)

Thursday, June 18, 2009 #

Communicating, Technically Speaking

The goal of an information professional is to communicate ideas to another person that enables that person to apply the ideas to their own goals. Communication is a three-part process, as follows:

1. Form an idea or concept.
2. Transmit the idea.
3. Receive the idea.

Despite the fact that forming and transmitting ideas come from a single person, some people can have trouble articulating exactly what they conceive in their minds; that creates a (sometimes significant) change in the message before it gets transmitted to the receiver.

The receiver poses yet another challenge to the communication process because the message is interpreted through the filters of personal experiences and biases, and the receiver’s ability to comprehend the message.

The better technical communicators understand how to express information in ways that carry the message from conception through reception. An axiom along these lines is "say what you mean, and mean what you say."

Mark Metcalfe

Posted On Thursday, June 18, 2009 4:46 PM | Comments (0)

Wednesday, June 17, 2009 #

The Qualities of a Good Documentation Manager

I was a technical writer for 16 years before managing technical writers. We are a peculiar bunch of folks - kind of like the high school band - talented, but a little quirky. Most of us are introverted and we get our kicks from composing information that people find useful. (I am one of the extroverted ones.)

While writers focus on their products, a writing manager has a broader focus on the corporate brand. A manager that merely maintains the status quo, by having the team update operational information, is not producing good documentation. After nine years of managing people who are cut from the same professional cloth as I am, I reflect on the following qualities of a good documentation manager:

Innovation and leading-edge technology use employs new techniques to transfer knowledge better. For example, multimedia content lets a customer watch a 3-minute demonstration rather than having to read several pages of documentation. (It has the added benefit of keeping writer skills current in a competitive market.)

A long-term vision develops a well-architected information system, plans a phased evolutionary path, and steadily executes on the plan.

Customer focus involves finding out what customers think that they want, but also markets the value of documentation to the customer. It is a proactive approach that communicates to customers that we understand their wants and needs, and respond to them, and include innovations that they should like.

Initiatives drive internal process improvement, such as defining best practice content, developing short-term and long-term strategies, working with internal and external customers for value-added documentation, helping to produce marketing brochures, just to name a few.

A proven track record of quality shows up in awards and other forms of recognition, indicating a pattern of excellence.

I am certain that other successful managers can add to my list. I will only add that I believe it is imperative that a technical writing manager understands technical writers and the value of content development to the company, even when others in the company cannot quite understand how good documentation affects the bottom line. (I have already blogged about how poor documentation definitely impacts the bottom line.)

Mark Metcalfe

P.S. I played first trombone in the school band.

Posted On Wednesday, June 17, 2009 11:18 AM | Comments (0)

Tuesday, June 16, 2009 #

List of Information Types

Thanks for the comments. Here is a more complete listing of information types that is extensive but not exhaustive.

Disposable information: Installation information such as wizard text, liner notes in a CD Jacket, and temporary information (passwords). Product Notes to tell the customer what is new in a version of the software. Getting Started, which is information in a small document (~20 pages) to familiarize someone with the product (in-depth information available elsewhere), or a high-level tool tour (which can be text or multimedia).

Reference and Quick Help: Road map that provides all-points access to the information set (that is, an index of sorts); information accessed from the Help menu and Help buttons. Web Information such as frequently asked questions (FAQs), knowledge database (user communities), known problems and workarounds; in addition to the rest of the information set available online. Reference Help such as procedures, command information, examples, descriptions, summaries, and glossaries.

Competence training: Tutorials that show an example use of the product from start to finish, or provide an online, interactive way to learn how to use the tool. User guides provide in-depth information about using the tool including complex reference information. Methodology guides provide tool-neutral introductions to new technologies. Flow documents describe "zero-to-goal" paths for using the software. They can also provide tool-to-tool migration of data for projects that require more than one tool to generate a product. Best Practices describe recommended uses of a tool. Expert papers also can describe specific successful uses of a tool.

Mark Metcalfe

Posted On Tuesday, June 16, 2009 9:45 AM | Comments (0)

Monday, June 15, 2009 #

Types of Learning

There are two fundamental reasons why people learn about something:

People learn to accomplish a specific task.
For example, a recipe for baking a chocolate cake contains specific instructions.

People learn to acquire knowledge, which can be applied in more than one way.
For example, a reference for baking techniques (perhaps at different altitudes) will contain concepts related to baking (the textures of certain breads, the right way to use yeast, and so on).

When the information professional understands ways that people learn, a number of methods are available to accommodate the various ways of learning. The following examples describe two ways to teach a person:

Progressive disclosure teaches a person by building concepts on the foundation of other concepts. For example, learning to count comes before learning adding numbers, which comes before learning to multiply numbers. Calculus cannot be taught without first laying the foundations of fundamental mathematics.

Rote reinforcement teaches a person through repetitive action. For example, an assembly line worker becomes more productive as repetitive action improves the skill.

Note: Both methods of learning may teach a person that 7x7=49. One person may add 7 seven times while the other looks up the answer on the multiplication table. If 7x7 is referenced with sufficient frequency, a person can “learn” that 7x7=49; the answer is available without needing the fundamentals of mathematics. But this kind of learning does no good if the equation changes to 17x8 or needs to be related to higher mathematical functions.

Mark Metcalfe

Posted On Monday, June 15, 2009 11:43 AM | Comments (2)

Friday, June 12, 2009 #

Types of Information

The information professional must employ several ways to communicate ideas because people have different ways of processing information. The considerations that determine how information should be presented depends on such things as human factors, user experience, and behavioral preferences of the consumer, plus the technical depth, volume, and complexity of the information.

In the broadest of terms, information has three main distinctions: disposable, point-of-need reference, and competence training.

  • Disposable information is necessary when there is a need to acquire temporary knowledge to accomplish an immediate goal. For example, a person gets a temporary password for a single login session. The password must be transmitted and received, but it does not need to be retained after use. We provide some necessary types of one-use information such as installation help and guides, which becomes unnecessary after one completes the installation.
  • Reference information at the point-of-need is important for the experienced user who needs specific information to continue working. Usually, reference material is uncomplicated and should assist the experienced user by filling in gaps of knowledge.
  • Training can take a number of forms, including single-use quick starts, comprehensive user guides, focused tutorials, and abstract methodologies; each information type is designed to develop proficiency. By contrast, proficiency is not the goal for disposable or reference material.

There are many finer distinctions, but it all comes down to providing the right information at the right time.

Mark Metcalfe

Posted On Friday, June 12, 2009 12:43 PM | Comments (0)

Thursday, June 11, 2009 #

Nobody Reads the Documentation vs. RTFM

"Nobody reads the documentation," is something I hear a lot. There is another adage in software development that says, "if software is developed properly, then we won't need documentation." This may be true, I do not know, but since I've been in this profession for so long, it may be true that precious few software products were developed properly.

However, (even as a documentation professional), I readily confess that I too tinker with software before I resort to reading about its features. There is much to be said about intuitive interfaces reducing the need for information about a product.

Sparse documentation may be fine for simple products with targeted functionality, but complex software that is "feature rich" is more likely to need information about how a user can go from dabbling to dazzling. This is where RTFM ("read the fine manual") comes in.

If documentation is so-so, people access it only when they need to, because most so-so documentation is operational, focused primarily on describing the features of a product instead of how to put the product to good use. So-so documentation can perform only somewhat adequately. It never receives praise, but it will be criticized when it does not meet minimum requirements or expectations. So-so documentation damages the product (and company brand) by conveying the perception of inferior quality.

If documentation is well-written (and useful), people access it more often because they want to and because the information communicates and relates information in ways that people want to learn. Well-written documentation performs its function of making people productive (and occasionally gets praise).

Mark Metcalfe

Posted On Thursday, June 11, 2009 11:34 AM | Comments (0)

Wednesday, June 10, 2009 #

Technical Writing Blog

Hello. My name is Mark Metcalfe and I have been a technical writer and technical writing manager since 1984 when cut and paste meant scissors and tape. A lot has happened in and to the world of technical writing since then. In 1984, most technical writers came from backgrounds like education, biology, English majors. I have a bachelors degree in computer science and there were precious few of us then. It seems that anyone who could show writing prowess could get into the technical writing field. It did not take long for colleges and universities to offer certificates in technical writing. Experience began to build, groups formed, and conferences convened.

The value of technical writing is sometimes difficult for some companies to see (even to this day) because anyone can slap together a description of software. Some people in other functions are very good writers, and some technical writers do little more than warm over product specifications. Regardless, customers evaluate the overall quality of a product, including how well it is documented. When the documentation is well-written and organized, then it performs its job (and most customers take no notice). If the documentation is poorly written or poorly organized, it reflects poorly on the product and can cost the company real money in customer service calls. Most people do not know good documentation when they see it, but almost everyone knows bad documentation.

Today's documentation is being globalized. Due to the high cost of labor and the economic backdraft that led companies to cut US writing staffs, one of my previous employers opened offices in India more than a dozen years ago. Now those offices are primary generators of documentation. India is feeling the pinch from China, Russia, and other places, even in the Technical Writing field, where English is still the primary language for product information.

Technologies have advanced and so have release deadlines for documentation. In 1984, manuals had to be completed and closed for weeks before the software release to be able to manufacture, print, and store the manuals. Today, companies are striving to convert their legacy documentation into rapid-access topics. What is ready at release-time is quick starts and reference material - necessary for early adopters of the software - but writing continues following the release to be ready for the mass adoption of the software. The mass audience needs more in-depth training and easier-to-consume information. Text only is also becoming passe in a YouTube consumer environment.

The Technical Writer (a good one) possesses the skills to organize, prioritize, and convey information, but that person also needs to adapt to new technologies for better, rapid access to just-what-I-need, or just-what-I-want information about a product or service.

I intend to use this blog to document things related to the technical writing field to generate an appreciation for content development in our current time.

Mark Metcalfe

Posted On Wednesday, June 10, 2009 4:42 PM | Comments (3)

Copyright © TechnicalWriting

Design by Bartosz Brzezinski

Design by Phil Haack Based On A Design By Bartosz Brzezinski