When creating online help or user assistance, a common practice is to include a related topics link at the end of a given topic. The link usually appears as a clickable button labeled Related Topics or See Also. When a user clicks the button, a pop-up list of related topics appears, as shown below. Each topic is a clickable link.

In MadCap Flare, you can create this type of link using help controls. Flare offers three types of help control, and my favorite is the Concept Link. This control builds a dynamic list of topics that are associated by a concept. You first have to insert concept markers into the topics to create a concept association among them. This type of linking relationship is similar to A-links in other help tools.

Inserting a concept marker

Before you insert a Concept Link help control into a topic, you need to add a concept marker. To insert a concept marker, follow these steps:

1. Open the topic.
2. Open the Concept Window: View > Concept Window.
3. Do either of the following:
   • Add a new concept term by typing it in the entry field at the top; or
   • Select a previously added concept term from the list in the lower half of the window. For each existing term, you can click the plus sign (+) to the left and view a list of topics that are associated with that term. You can also drag terms into the open topic to create new markers.

I usually place both concept and index markers at the very beginning of a topic, before the topic title.

Creating a pop-up concept link

Now that you have created concept associations among topics by adding markers, add a concept link to the end of each of those topics. This procedure creates the pop-up link that users see in your help output.

To create the pop-up concept link at the end of a topic, follow these steps:

1. Open a topic that contains a concept marker.
2. Select the following menu command:
   Insert > Help Control > Concept Link (A-link).
3. Select a term on the right.
4. Click the directional button in the middle of the window to copy the term to the left side of the window.
5. Click OK.

Other types of help control

Flare offers two other types of help control. You’ll find both of them using this menu command: Insert > Help Control > [Type of Control].

Related Topics control

This control enables you to manually build a list of related topics by selecting files. The control appears as a button with the label Related Topics.

For more information, see these help topics:

• Inserting Related Topics Links into Topics
• Editing Related Topics Links

Keyword Link control

This control builds a dynamic list of topics that are associated by an index keyword. You first have to insert index markers into the topics to create a keyword association among them. The default label for the control is Search Index.

For more information, see these help topics:

• Inserting Keyword Links into Topics
• Editing Keyword Links

Another Option: Relationship Tables

When MadCap introduced DITA publishing capability in Flare 5, they cleverly integrated DITA relationship tables as yet another way to introduce related topic links. You can use this powerful feature in non-DITA projects. For more information, see About Relationship Tables.

Questions?

Help controls and relationship tables enable you to give users a simple way to find related information. They also enable users to learn by association. I encourage you to use these features when using MadCap flare to develop user assistance.

If you have questions or comments about these techniques, please add a comment or contact me.

Back to top

My friend and fellow writer Kai Weber raises an interesting question in a post called “Does structured writing stifle creativity?” The migration to XML architectures has a lot of people asking similar questions.

I have long pondered a more broad version of the question: Is technical writing really a creative profession?

The inevitable cocktail party conversation

At cocktail parties and other social events, I often meet people who aspire to make a living in fiction writing, poetry writing, or graphic design. When they learn that I make a living in technical communication, they ask how they might become a technical writer. They’re attracted to the idea that they can at least make a living writing while they develop their creative talents.

I understand the idea and the logic very well. I come from a fine arts background. I have a degree in music education and performed in nightclubs and concert halls for years. I own copyrights for nine songs. I have dabbled in poetry and have a collection of unpublished poems in my filing cabinet. Unfortunately, I never had the drive to succeed in music or fiction/poetry writing. Passion, yes; drive, no.

I landed my first corporate job to support my musical endeavors. The education part of my degree paved my path to technical communication. I had been trained in educational psychology and understood how adults learn. I could write lesson plans. So when I entered the job market in the late 80s, I started developing courses and training mainframe users. With the increasing emphasis on technology over the years, I added technical writing to my skill set. I have straddled the instructional design and technical writing worlds ever since. Both disciplines appeal to my bizarre mix of left- and right-brained thinking. I’m creative but very methodical.

So how do I answer the cocktail party question? I respond with a question: What technical discipline do you want to specialize in? Technical communication comprises many disciplines: Science writers write about science. Medical writers write about medicine. Technology writers write about hardware, software, information security, and many other aspects.

Typical answers: “Well, I use a lot of software,” or “My degree is in biology.” From there, I try and make suggestions for resources, leading to an exchange of business cards. I also point out that technical writing is business writing and requires a lot of team interaction. It’s not a solitary profession where you are left alone to mine your creative imagination.

True creativity in technical communication

To wind up the cocktail conversation, I stress what I think is the number one requirement for succeeding in technical communication: creative problem solving. Writing is just one aspect of your work. You have the opportunity to apply your research and investigative skills to helping others.

Whether you are developing a knowledge base or a training video, your goal is to provide user assistance. By helping users solve their problems, you enable them to complete tasks and accomplish goals. I realize that this isn’t a new or original assertion, but it bears repeating.

For more information about how your work profoundly influences users’ daily lives, see the following post: Paving the Road to a User Utopia.

Interested in learning more about the Darwin Information Typing Architecture (DITA)? I recommend that all information developers at least break the surface. Regardless of whether you plan to adopt DITA, you can benefit from studying it. You can even borrow from its lean, efficient writing model.

I have been a fan of modular, “chunked” writing since I took an Information Mapping (IM) course years ago. Although I see value in using IM, I prefer DITA’s open, simplified, XML-based model. I appreciate its emphasis on standardization and content reuse. I like the flexibility for using specialized information types. Although none of my clients have adopted DITA, I study it because I have a driven fascination with information architecture and structure.

Toe in the water or swan dive?

Most of the available information about DITA is on the web, but at least three DITA-related books have been released (as far as I know). Each of the following titles is a great resource for neophytes who find the formal specification a bit intimidating but who would like to learn more about—and possibly even experiment with—DITA.

DITA 101: Fundamentals of DITA for Authors and Managers

This 2009 release is written by Ann Rockley, Steve Manning, and Charles Cooper, three esteemed members of the Rockley Group. The book provides a straightforward introduction to DITA without becoming mired in technical details. It provides an overview of the DITA architecture, explains the benefits, and gives advice for planning a DITA implementation. It includes just enough “Advanced Stuff” (the name of the final section) to orient you toward the language of DITA. Best of all, it’s written in the same crystal clear style as Managing Enterprise Content, also a Rockley publication and one of the best books on content management.

DITA 101 is a “toe in the water” book. If you need to make a business case for DITA or compose an elevator speech, this book is your best resource.

Practical DITA

Author Julio J. Vazquez places more emphasis on the planning and execution of DITA projects. In Practical DITA, he encourages authors to start with a visual map of their information set and refer to the map throughout the information development process. He emphasizes the importance of audience and task analysis.

Of the three books discussed here, Practical DITA offers the most detailed writing advice. Vazquez introduces the basic DITA information types and explains the role of each. For example, he lists questions that a concept topic should answer. He recommends that cognitive tasks be written as concepts. He emphasizes the importance of writing “generically” and limiting related links to external content.

Practical DITA also exposes readers to the basic mechanics of DITA. The author covers such specifics as semantic naming and common semantic elements, syntax diagrams and how to create them, filtering and flagging, and linking relationships.

If you are committed to DITA adoption or simply want to develop a test project, I recommend Practical DITA as prerequisite reading. This is your “starting to dog paddle” book.

Introduction to DITA:
A User Guide to the Darwin Information Typing Architecture

Introduced in 2006 by Comtech, this book is a comprehensive tutorial. After a brief overview of the DITA architecture and the core information types, it plunges headlong into hands-on exercises. You open your XML editor and build topic examples. You work with DITA maps. You learn techniques for content reuse and specialization. You install the DITA Open Toolkit and build output.

Introduction to DITA is your “starting to swim” book. This book is the choice for information developers who want experiential guidance in DITA content creation. You not only learn by doing, but you also become acquainted with many DITA elements. Although I recommend this book for practice, I give equal weight to Practical DITA for its sound advice.

Ready to take the plunge?

Good luck on your DITA journey! I have provided links for online DITA resources and for each of the three books discussed here. If you have additional resources or comments to share, please write.

Explore some online resources

• Learn more about DITA from the perspective of its creator, IBM
• Read the OASIS DITA Specification
• Visit the online community for the DITA standard
• Read the Wikipedia entry for DITA

Buy a book

• DITA 101: Fundamentals of DITA for Authors and Managers
• Practical DITA
• Introduction to DITA: A User Guide to the Darwin Information Typing Architecture

Back to top

As writers of technical content, we strive to help reduce the number of technical support calls. Yet, a recent post on the blog of LugIron Software refers to a quote stating that documentation can also increase the number of service requests.

Why?

Users feel overwhelmed

The first point in the quote states that overly comprehensive documentation scares users away. That may be true, but comprehensive simply means “of large scope” (Dictionary.com) and says nothing about the quality of the documentation, how it is organized, or how it is tuned for search.

If you deliver a voluminous, printed tome, users will most likely avoid it. If you deliver a help site without clear points of entry and orientation, users will probably look elsewhere. If your information is difficult to browse and search results are low to non-existent, users will give up.

You can improve the likelihood of user satisfaction by

• Performing a careful user and task analysis
• Single sourcing your content for modularity, reuse, and consistency
• Ensuring that your information provides maximum search returns
• Tailoring your information products to support roles and tasks.

For example, nearly all users can benefit from a simple Getting Started guide or tutorial. The guide can cover installation and configuration and then provide a basic orientation to your software. Emphasize what they can do with the software—not how cool the UI is. From there, give them branching options tailored to their roles and desired outcomes.

Users feel stimulated, but…

The second point in the quote bears repeating:

Documentation has so much cool stuff described, that it makes people’s imagination stimulated and they start thinking of other, even more exotic stuff they want to do but can not figure out and start a service request for it.

This statement is indicative of a damned-if-you-do, damned-if-you-don’t problem. I have to wonder how user assistance information has been presented and organized if it is perceived mainly as describing “cool stuff.” I also wonder how it’s structured. My earlier comments about organization, orientation, and findability apply in this case, too.

Regardless, the “cool stuff” aspect of software is a two-way street. If users want to improve the product or take it to another level, they need to provide feedback in the form of feature suggestions and enhancement requests. Product development teams cannot read their minds or restrain their imaginations.

Users feel enabled

Documentation that’s engaging should also make users feel that they have control. So how do you enable users without giving them too much?

You have created user profiles for your product, right? So why not ask “what type of user are you?” and give examples of typical users and associated tasks? Or ask “what would you like to do with Product X?” Then give readers some suggested branching points based on their roles and relevant tasks. Software and documentation need to be integrated in a way that provides a solution for getting things done.

Too often we waste a lot of words that over-emphasize the UI instead of including a separate UI reference section. If you find that you are constantly referring to the UI in ways that are not essential to performing tasks, then ask yourself whether the product design is truly effective or overly cumbersome. That may lead to a separate, challenging but necessary discussion for your product team.

Users feel involved

Our industry is buzzing about ways to get users more involved in contributing to product documentation by applying their product experience. Give them a voice and a stake in the process.

I completely support this approach. As a user, I rely heavily on active, peer-to-peer forums that not only share troubleshooting information but also “cool” tips. I understand how such forums can lessen user frustration and generate user excitement.

If you implement a process to enhance your documentation with user-generated content, don’t be surprised if the regular contributors comprise a small subset. Many users just want to use the product to get their tasks done. They don’t want to write the documentation. So even your participating users need to understand that the documentation must motivate, engage, and most importantly, provide answers for all users.

Even when user-generated content becomes part of your process, someone must manage it and ensure that it is accessible and usable. The most effective forums in which I participate have strong leadership.

Users feel bored

Regardless of what motivates or scares users away, I believe that our industry overlooks some of the obvious reasons why documentation often sucks. One factor that we ignore is the pervasive, stodgy writing style.

Companies should take a long, hard look at their style standards, or lack thereof. In this day and age of more casual conversation, why not integrate a more conversational tone into your documentation? As a long-time editor of tech docs, I have lobbied for a less formal tone for years, and I’m a lot older than many of my vibrant young peers.

Examples:

• We continue to write about how software “allows” or “lets” users accomplish a task instead of how it enables them. The only contexts for the word allows are access and security. And in a software context, I think that “lets” sounds ridiculous.
• We write “If you wish to…” before notes and tasks. We’re afraid to use the stronger and less formal want, or simply the infinitive form: To do x, click y. Wish connotes longing.

  Read: “When you wish upon a star…”

  I’d wager that while using our software, users are longing to finish work and go home. Do you ask friends or colleagues if they wish to go to lunch?

• We use may instead of the stronger, more enabling can. This usage sometimes creates confusion about whether we are giving permission or expressing that something might happen (as in maybe).

These examples are often defended as “polite” usage. I simply believe that they make our words far less engaging and even a bit dull. They create the impression that software is controlling users instead of putting them in the driver’s seat.

Of course, software documentation isn’t the only kind of technical writing. Making policies and procedures sound more informal isn’t easy. Writing about the installation and operation of heavily regulated equipment is a serious business where inaccuracies and mistakes can have serious consequences. But I still believe that even those types of writing can benefit from clear, plain language that sounds more natural.

I’m not advocating a departure from formal writing, but I believe that we are redefining our definition of what’s formal. I have often wished—that is, longed for—a change, and I welcome it.

But I digress. Plain language is a subject for another post.

Users feel content

The rise of social media brings new possibilities and new challenges that are making us rethink how we provide user assistance. Regardless of what we try and what we find effective, we need to remember that what we are delivering is user assistance. The bottom line is, users use our products, read our policies, install, configure, and operate our equipment for one purpose: to get things done.

So when you develop information for users, keep these things in mind:

• Give them a clear orientation so that they can decide where they want to go.
• Stop focusing on the “cool” factor of your product.
• Strive to increase the likelihood that they will find what they’re looking for.
• Consider their roles and provide tailored information.

I welcome your comments and hope that you will share your own solutions for creating a better user experience.

Back to top

Fellow writer Tom Johnson has written several excellent posts on the value of quick reference guides as a concise job aid. He has also given great advice on best practices for developing them. If you need to create quick reference guides, I highly recommend Tom’s recent post, titled Quick Reference Guides: Short and Sweet Documentation.

Tom mentions the four basic principles discussed in one of my favorite design books, The Non-Designer’s Design Book: Design and Typographic Principles for the Visual Novice, by Robin Williams. (No, this isn’t Robin Williams the comedian, though Ms. Williams can certainly be irreverent and entertaining.) The post also mentions Robin’s useful mnemonic device for learning the four principles:

• Contrast
• Repetition
• Alignment
• Proximity

CRAP. Got it?

The missing principle

When studying and evaluating the presentation of content, I generally find that designers of all levels seem to follow the four principles to a great extent. They seem to understand the need for contrast and repetition. As for alignment, I could write volumes about the abuse of centered text, though it’s not as rampant as it used to be. But I find that the design element that is often lacking or absent is proximity.

Regarding proximity in visual design, Williams says

If items are related to each other, group them into closer proximity. Separate items that are not directly related to each other. Vary the space between to indicate the closeness or the importance of the relationship.

This seems simple and logical, doesn’t it? Yet, since the early days of the web (pre-CSS), I often see amorphous layouts like this one:

You can probably guess which paragraphs are headings, simply because they are single lines and are set in bold text. There is certainly some semblance of structure. But observe the amount of space between headings and body text. Also note the weight of the headings. Are they all at the same level? When you scan the blocks, does your eye find a resting place? Can you easily identify the relationships between chunks of text?

Bold headings are at least a start. There’s contrast. Good. Now let’s add proximity to the text by following Robin’s advice and grouping the paragraphs:

This is a subtle change, but we can now more easily recognize the information blocks. The first heading also looks slightly larger and heavier, suggesting that it is a first-level heading.

The Gestalt of clear text

If you search the web for information about proximity in visual design, you will find that most of the writing and discussion centers on the effects created by the grouping of figures and forms. This is the key aspect of Gestalt theory. Although proximity certainly plays a key role in our perception of graphic elements, I believe that it is equally important in the visual and perceptual organization of textual content.

Ben Hunt of Scratch Media agrees. In his post on Grouping elements for clear web page design, Hunt includes paragraphs and margins as important elements in successful page designs. I especially appreciate his assertion that

Grouping needs whitespace, its opposing force, to exist.

Proximity may seem like a small, insignificant design aspect, but it is a key principle for structuring information and promoting comprehension. When you are creating content for print or the web, pay attention to how you block the information. Regardless of the tool or technology that you’re using—Word, FrameMaker, InDesign, or CSS—you can easily use grouping and spacing to show relationships. Hint for CSS designers: Under the Box property group, look for margin-top and margin-bottom.

Related references

• Wikpedia on Gestalt psychology
• The Gestalt Principles
• Basic Web Page Layout and Design (tutorial)

Back to top