You’re reading an “honorably mentioned” blog!

Mark Fidelman over at MindTouch has put together the Top 25 Most Influential Technical Communicator Bloggers. And I’m tickled speechless because I got an honorable mention! Not bad for someone who started barely half a year ago and blogs one or two posts a week… 🙂

I know most of the people who made the list, either through blogs, webinars and twitter or in person. In fact, many are on my blogroll in the side bar. I’ve learned a lot from them, so I recommend you check ’em out!

Well done, Mark, thank you!

Buy yourself time as a lone writer

If you want to be “making it as a lone writer“, one of the most difficult challenges is to find time. Time to develop your skills, improve the documentation, advocate it and network with other teams. One comment on my previous post raised that issue, and I’m taking a couple of posts to reply. Jim wrote:

I am a lone writer for three separate product lines that are mostly custom products (only half are standard manuals). None of these products lines are planned. I hardly have enough time to finish what is required, let alone look ahead to the future of my “department”.

My strengths are technical understanding and an ability to communicate with a technical audience. Weaknesses in planning and management.

So without divorcing my family and marrying my career, do you have any suggestions for employing the suggestions you offered to my situation?

Good question and good point! Today and next week, I present some strategies that have worked for me. They have bought me time to get organized, so I could produce better documentation more efficiently.

Eliminate internal inefficiencies

When you’re a lone writer, chances are you’re not working as efficiently as you could. I know I didn’t, and it wasn’t because I was lazy or incompetent. The “benign neglect” that surrounded documentation simply put a low priority on efficient documentation. As a lone writer, you are probably the first and foremost advocate to make documentation more efficient.

Moving to(wards) topic-based authoring is one good way to become more efficient. When I was a lone writer, no one in my company knew about topic-based authoring (or “TBA”; here’s a good first introduction). I didn’t know about it either, so I wrote user manuals in long Word documents with long chapters. They were hell to maintain: For each error, each update I had to sift through the whole document to find all the places that needed editing. Lone writers can benefit from TBA in these ways:

You can structure your documents using TBA, so most information is only in one logical place. This can help you to limit the scope of your updates from one release to the next. In a first stage, it might already be helpful just to chunk your chapters smartly:

  • Move all conceptual “what is…” sections into one chapter.
  • Move all the procedural “how do I do…” sections into other chapters.

You can introduce TBA incrementally as a lone writer, so you don’t need extra time to reorganize all content at once. And you can take it slowly as you become more confident about how to do it.

You can reuse topics. Even if you have custom products (like Jim above), look closely at them: Are they always completely built from scratch? Maybe they reuse some concepts, elements or workflows that you have documented before. You can isolate such documentation into topics and reuse them.

You don’t necessarily need a cool authoring tool for TBA (though your reuse won’t be efficient without one). The first goal is to get your content organized, so you can quickly identify and edit the few topics affected by each functional change or update. I’ve done TBA in Word more often than I care to admit… 🙂

You pick up a marketable skill: You’ll find it easier to get and move into a new job if you know TBA. In my experience, knowing such a method is more valuable than knowing any one tool. The method still applies while skills with an old tool version have become obsolete.

– You might also find other ways to tackle inefficiencies in the way you work today. Even if it’s only a more efficient way to prepare your weekly reports.

The strategy to eliminate internal inefficiencies has an evil twin which can be just as effective, but it’s more dangerous:

Skimp temporarily

This one is risky, it requires courage, good judgment, and some mutual trust!

When I was a lone writer, I have gotten away with skimping temporarily.  The requirements on my documentation were not standardized. Sometimes, the only formal requirement was that documentation exists. If you’re in such a situation, you may be able to get away with underperforming for one or two releases, while you get organized.

When I did this, my manager indirectly called me on it and suggested some improvements to the documentation. Then I was able to show him how I had started to move towards TBA to be more efficient in the future. When he realized that I was working on larger, reasonable improvements, he supported me.

– Next week, I’ll talk about a couple of strategies to buy yourself more time: You can also fight external inefficiencies which encroach on you from other departments.

Your turn

What is your experience when trying to improve documentation? Have thesse or any other strategies worked for you?

How to wash George Harrison’s car

This is from 1962 when George Harrison was trying to break into tech writing, playing guitar on the side. He’s not bad for a 19-year old. To wit:

  • He presents the procedure step by step.
  • He uses the imperative for clear instructions – though he lapses into conditional “should”s occasionally.
  • He speaks to his reader’s needs and allows her to interrupt the procedure for a cup of tea – twice!

So the world lost a promising tech writer – but gained a wonderfully imaginative guitarist. Well done, George! And thank you for the music.

Making it as a lone writer

Lone writers have their work cut out for them. But the lack of processes and resources also gives them flexibility and freedom to work towards improving both, the documentation and their situation.

The plight of a lone writer

Life’s difficult for lone writers. They are usually the only person in the company who creates and maintains documentation. They are tucked in with the marketing or development department. They often operate without a dedicated budget or specific managerial guidance.

(Photo by jc-pics)

However, such “benign neglect” which treats documentation as an afterthought also offers opportunities – which are best exploited by the tech writer. After all, part of the problem is that many managers don’t fully understand what tech communicators could do if they let them. And change management is much easier when you only have to worry about management buy-in and not employee buy-in, too.

The promise

It’s a lot of work for a lone writer to re-invent how documentation is done and perceived at your company. It once took me a couple of years to get from a shaky reputation due to unmaintainable Word manuals to appreciated documentation written with MadCap Flare and delivered as web help as well as printable manuals and tutorials in PDF.

But if you’re up for it, it can be very rewarding, too. It can

  • Increase the value and raise the profile of documentation
  • Make your job more interesting, more diverse
  • Secure your job in the mid-term
  • Secure your career in the long term

A matter of type

There’s no one sure-fire way to do it. To give you the best odds, take into account your personality: Many of us tech writers are introverted types (else we might have gone into marketing or training… 🙂 ) If you are introverted, focus on your work, and let it speak for itself – but put it somewhere your colleagues can “hear” it!

If you are a more extroverted type, consider giving documentation a face – your face! You’re it, anyway… If you know you do good work, you might as well reap the rewards rather than amble along in anonymity.

Focus on your work and your strengths

Regardless of your type, I’ve found that these four strategies can contribute to raising the profile of documentation:

  • Manage your work efficiently
  • Make your work easy to use
  • Know your strengths
  • Leverage your strengths

These four things are basically what a good manager should be doing for you. But none are so difficult that you can’t learn them and apply them for yourself.

Learn more…

To learn more about making it as a lone writer, especially about implementing the strategies, check all posts about “lone writers”.

Update: Two posts about buying yourself time as a lone writer have appeared since this post was published. Check out part 1 and part 2.

If you’re attending the TCUK conference in September, try to catch my session “Getting ahead as a lone author” on the morning of Wednesday, September 22.

Your turn

What are your experiences as a lone writer? How have you been able to raise the profile of your documentation? Can you imagine that the strategies above could work for you? Leave a comment!

Learn from your topics and collaborate

We tech writers can learn from our chunks of content: What makes a topic successful can also make us writers successful! I had this idea while reading one of my favorite management blogs, Jurgen Appelo’s

In a recent post, Jurgen talks about what turns a bunch people into a team: It’s a shared purpose and a common identification as an entity. (Duh, so far… – But here comes…) This, Jurgen says, is also called “chunking”.

The chunking principle

“That’s like chunked topics in topic-based authoring,” I thought immediately and started to sort out more parallels:

  • A team is self-contained and has an identifiable purpose that distinguishes it from other team, just as each topic does. (Though we humans can belong to several teams consecutively or at the same time, so we can lead more interesting lives than our topics…)
  • Teams, such as tech writers, create context by connecting to other related teams, such as trainers, testers, interface designers, information architects, content strategists, etc., just as topics link to related topics.
  • “Teams don’t operate well when people don’t know what the teams are, and who they can rely on,” Jurgen says. Your collection of topics won’t play nicely, either, if it’s not clear what the other topics are and whether readers and writers can rely on them.

Jurgen goes on to emphasize boundary management of teams that helps to ensure that teams can work well and efficiently. If you’re at all interested in team management, check out his post – and his blog as a whole.

Collaborate like topics

I think there’s a lesson for tech writers here beyond team management: How successful you’ll be in your work as a tech writer depends on how well you define your job’s purpose and communicate it to others:

  • Be clear in what you need from product managers, from developers, from subject-matter experts and when and how you need it.
  • Be clear in what you can offer to training (content for training materials), to product management (fact checking and editing of brochures), to testing (written use cases).

In short: Do like your topics and collaborate! Given that we tech writers are communicators by trade, we shouldn’t find it too difficult to speak out on our own behalf. 🙂

Your turn

How important is it to your success that you collaborate efficiently with other teams? Do they understand what you do and how you work? Please leave a comment.

Managing: Instruction vs. communication

I’ve found an enlightening opposition in Jurgen Appelo’s presentation “The Dolt’s Guide to Self-Organization“, slides 54-55:

Managing a lifeless system is all about instruction.
Managing a living system is all about communication.

What struck me was that we tech writers often consider task-based instructions in documentation already better than feature-based system description.

But seen from a managing perspective, Jurgen reminded me once again that instructions are at best an intermediary step on the way to a good user experience.

Index this!

An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions.

In this post, I share my best advice about building an index. And I ask for your help and opinion on a couple of details.

To make your index entries helpful, anticipate user searches. Think of it as a parallel to online search results. When building an index, think primarily of what users might want to look up and find in your documentation.

To create an index, follow these three steps:

  1. Create index entries.
  2. Build the index.
  3. Clean up your index.

1. Create index entries

  1. Scroll through your entire document and search for words and phrases that you want to appear in the index. Select only occurrences with substantial descriptions, not just mere mentions.
  2. Create an index entry, depending on your help-authoring tool or other software. Edit the entry to avoid all unnecessary words, such as articles (“a” or “the”) and prepositions (“in” or “by”, etc.).

When creating index entries, consider these issues:

  • Redundant entries, where you have several entries for the same thing, may seem wasteful and confusing. However, if users are likely to search for the word “equity” in addition to “stocks”, consider using one of the terms to refer the reader to the other entry.
  • Cross-references between index entries is a suitable compromise between usability and completeness: Of course, it is an extra step for the reader to move from the entry “Equity: see Stocks” to the “Stocks” entry. On the other hand, it is much more difficult for writers to keep both entries “Equity” and “Stocks” complete and identical over time. Which do you prefer, as a reader and as a writer: Is it okay for readers to move to a second entry? Or should the page numbers be at each entry?
  • Nested entries can help you to structure your index and alert the user to hierarchies of concepts and functions. It also cleans up your index by avoiding redundant words. Don’t have more than two levels, however. What’s your experience: Are nested entries helpful or generally confusing to readers?

2. Build the index

At any time after creating your first index entries, create and preview your index, depending on your help-authoring tool or other software.

3. Clean up the index

After you have created all index entries, rebuild and update your index. Then review the existing index for inconsistencies and go back to the index marks in the text to correct the following issues:

  • Omit double entries of the same term, but with different spelling or singular and plural.
  • Break up index entries that list more than 5 target pages. Refine index entries, for example by creating additional second-level entries for separate tasks, such as “Setting up”, “Calculating”, etc.

Optimal length and scope of an index is the result of a compromise: Make your index as long as necessary to support readers to use your documentation quickly and efficiently. And make your index as short as possible to spare yourself unnecessary work and the reader confusion.

Whether your index is too long or too short is a matter of judgement. Put yourself into the reader’s shoes once more and review your index. You may find that your index is a little too short and missing some terms that users might also look up.

Read more

Good resources for building an index are these two web pages and three books:

Your turn

Please help me out by weighing in with your experiences and opinions to the questions above. Or feel free to tell me if  I forgot anything? How do you create an index for printed documentation? Should online help also have one, or is the search enough? Please leave a comment.