Getting ready for TCUK

Take half the slides and twice the nerves.

That’s the lesson I learned as I spent last week getting ready for the TCUK conference and my presentation “Getting ahead as a lone author”. (The lesson is a variation on the old travel advice “Take half the clothes and twice the money” which was useful before credit cards and ATMs…).

Finishing the presentation

… took much longer than I thought. Basically, it’s just as writing good documentation: Knowing what you want to say is a prerequisite. But saying it in the most effective way is what takes time.

But it was worth the trouble. When I was done, I had a nice presentation: A catchy introduction nicely segued into an elegant sequence of nine best practices, followed by a concise summary and conclusion. 30 minutes, plus 10 minutes for Q&A, didn’t seem so terrifying anymore.

If you’ve presented before you probably worry now. It took me some practice to find out what you already know:

30 minutes is much shorter

… than I thought. There’s no way to fit all this into 30 minutes. So I spent more time yet on taking stuff out again. I conflated 2 of the 9 points and dropped another 3, so I’m now down to 5 best practices. That clocks in at around 30 minutes.

Again, it was worth the trouble since I’m now sure I have the best, most focused content ready to present. Highlights include a painting by Carl Rakeman and the “Kick Ass Curve”.. 🙂

If you attend TCUK, consider attending my session on Wednesday at 10:00, right after the keynote address. If you don’t, stay tuned, there will be post-conference notes in this space!

Welcome to summer reruns, part 1

My blog and I are taking it a little easier towards the end of the summer.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a walk on the beach… 🙂

As we’re gearing up for the new season, here are some reruns from the last year or so.

Popular posts from my blog

Trends in technical communication 2010

This is one of my two most popular posts by far. With the help of several readers, we’re commenting on and discussing two trends from a Scriptorium webinar “Technical Commmunication Trends for 2010 and Beyond”. Sarah O’Keefe predicts that it will include content curation. And Ellis Pratt proposes that technical communications will soon also shape an emotional user experience. Incidentally, Ellis will speak on the same topic at TCUK, so go see him, if you have a chance!

Making it as a lone writer

This is the first post in a small series where I share lessons learned and best practices how lone writers can get ahead. Incidentally, I will speak on the same topic at TCUK, so come see me, if you have a chance!

Reading outside the tech writing box

I’ve found that reading helps my writing, even off-topic reading. Technology journalism works especially well for me. I share my favorite magazines and anthologies and link to five articles that you can read online.

Noteworthy posts from elsewhere

Speaking of reading around. If you want to read up on neighboring disciplines, I recommend these three excellent posts:

Complete Beginner’s Guide to Content Strategy

Complete Beginner’s Guide to Information Architecture

Standardized Approaches to Usability

How and why to estimate writing efforts

Estimating your writing efforts and deadlines is difficult, but essential.

Can you reliably estimate the time you need to write documentation? And the date when you can deliver? It often seems a daunting task because it depends on many external factors:

  • The quality of specifications and designs.
  • The availability of the finished product.
  • The accessibility of subject-matter experts.
  • The punctuality and diligence of reviewers.

It also seems futile to spend time estimating efforts when you know you don’t have enough time anyway. But even though it’s difficult and takes time, I recommend that you do it.

Why estimate?

If you don’t do it, someone else will make assumptions about your schedule. Even if you’re just left with the ever decreasing time between delayed development and scheduled shipment.

Estimating makes documentation accountable, in both senses of the word:

  • You can explain the time you will spend on documentation. So it allows you to plan and budget the time. Share the estimates with your manager, and you can also share responsibility for the efforts.
  • You can also be held accountable for the time you have spent. With estimates, you only will have to justify the specific difference that you ran over the plan. That’s much better than arguing about the complete time which may “seem kind of long” to your manager, though you know “that’s just how long documentation takes”…

Estimating makes documentation more transparent, in other words. It gives you and other stakeholders specific numbers to talk about ahead of time. It gives everybody more control over the documentation process.

For example, I once faced the complaint from product managers that documentation held everything up, that we could ship sooner, if only the tech writer got his act together. By introducing estimates and refining the reporting, I was able to show that it was specifically the reviewers which held up the process. Everybody took the estimated time, more or less, but reviewers delayed their tasks unduly. In fact, one late reviewer was a product manager who had voiced the complaint…

What to estimate?

You get what you measure and estimate. Or in the words of Tom DeMarco: “You can’t control what you can’t measure.”

If you estimate number of pages per day, you’ll get reams of paper. But that doesn’t guarantee that the documentation is useful and/or accurate.

If you count the number of features, options and buttons and base your estimate on that, you’ll get a thorough description of the user interface. And a customer who says, “Don’t tell me how it works, tell me how to use it.”

Apply task-oriented writing and estimate topics, instead:

  1. Look at the specifications and designs to understand what’s being developed or produced from a user’s point of view.
  2. Distill or translate what you find:
    • Identify modular concepts that users will need to know. A microwave convection combination oven can use descriptions of both concepts with their principles and different use cases.
    • Sketch out user workflows to set up and operate the product and break them down into individual procedures. That oven’s manual will probably have procedures to set it up, to thaw frozen food, to heat food (using the microwave), to bake stuff (using the convection), and to clean it.

A high-level view of the topics and their complexity allows you to make a rough estimate how long you’ll need to create useful topic-based documentation.

How to estimate?

Estimate efficiently. I once estimated a one-month project so well, I was off by two hours in the end. The problem was that it took me two days to crunch all the numbers… I can’t recommend that.

So don’t try to be 100% accurate in your estimate, if it takes you a long time to do it. Here are a few ideas to spend less time on estimates:

  • Look at past efforts: Most likely, you’ll do some reporting anyway. Use this as the basis for future estimates. Maybe you’ll find an average time you take to write a concept topic. And one time period for easy and short procedures and another for more complex ones.
  • Refine your estimates and average sizes over time: No need to get it perfectly right the first time, especially, if you start estimations on your own account. Try to run the numbers beneath the radar before you come forth with them.
  • Trust the law of averages: What extra time you need for one topic, you’ll probably save on another.
  • Trust your experience: After a while, you won’t need to sketch out individual topics. You’ll be able to take an adequate measure from looking through the spec or design.

Further reading

To learn more, check out:

Your turn

Do you estimate your efforts ahead of time? Is it worth the extra effort? How do you use the numbers to your advantage? Please leave a comment.

Buy yourself time as a lone writer, part 2

To be “making it as a lone writer“, you need time. Time to develop your skills, improve the documentation, reach out and network with other teams.

Last week, I talked about some strategies to buy yourself time. You can, for example, move to(wards) topic-based authoring. This eliminates internal inefficiencies, namely those you can deal with yourself.

To buy yourself time, you can also try to:

Fight external inefficiencies

These are inefficiencies that encroach on you from other teams and give you a hard time. Here are two common examples:

Don’t test the product when you should be documenting it. It’s late in the production cycle, and you’re already looking at a tight schedule. You really have to start documenting now to ship on time. And then you find bugs and inconsistencies in the product and interface all over the place…

Testing as a lone writer is not a bad thing as such. Often, it’s what makes the job so interesting and diverse. The problem is if the time isn’t budgeted. Make sure such time and efforts are accounted for. If you enjoy testing, make sure your manager knows you’re doing it, and that it you need extra time for it.

If you cannot test efficiently, or if it’s actually someone else’s job, try not to do it. Yes, “we’re all in this together, and we have to cover each other’s backs”, but that shouldn’t mean that you pick up all the loose ends, just because you’re last in line. Being in it together doesn’t mean taking it out on the lone writer.

Time and again, I’ve “given back” products for testing along with a list of 19 bugs I’ve found in the first hour of documenting. Most managers actually understand that I cannot write documentation efficiently on unfinished or buggy products. To fix this problem, you might need to address a larger issue:

Insist that documentation is included in the project plan. Often, lone writers drop off the radar, and their efforts are not planned appropriately in the project plan or the production schedule. It should be, of course. Your manager and your project managers might not like to hear it, but good documentation takes an adequate amount of time. If they don’t believe you, let them compare measly quick starts that can be thrown together in two days with tutorials or manuals that might take two weeks or longer.

Lone writers are often not used to stand up for their documentation like this. Still, I’ve found it well worth the effort: You can start small by simply inquiring about the project schedule. Maybe you’ve heard about a strategic project or an important customer, and you want to make sure you can deliver good documentation along with it. It shows you’re taking an interest in the project as a whole and your position in it. Managers can’t push you away so easily, once they’ve understood your engagement will help their project – even if it means budgeting extra time.

Usually, project managers have pain points that you can appeal to: Maybe a certain level of documentation is part of the requirements, so it should be planned like any other part of the product? Maybe they’ll latch on to better documentation to buy themselves time and appease the customer? (They can’t very well say they need the extra time also for last-minute development and testing…)

Your turn

What other inefficiencies steal your time and energy? How do you cope with them? Feel free to leave a comment.

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?

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!

How you can manage your career…

You should manage your career as a continuous habit. – That’s the gist I got from a (re-)tweet by my friend Scott at DMN. I bring it into blogland where I can comment on it in more than 140 characters. Thanks, Scott, for bringing an excellent and relevant blog post to my attention!

Lance Haun’s blog Rehaul presents a great guest post by Steve Browne:

10 Career Management Tips In The Age Of Job Fear

Reasons why we don’t…

First, Steve gives some four reasons why we don’t manage our careers. What they have in common is that most of us seem to think of career management as occasional sprints – but not as a continuous habit.

I know this has been true for me: I would try and jumpstart my career management once I got really miserable in a job. Then it would be a lot of effort to make my past achievements presentable to others and to make my future vision clear to me. Which is, of course, only the first step…

Suggestions how we can…

Then Steve lists ten suggestions what we can do to manage our careers. They’re all great suggestions: They are actionable and real, so you’re not chasing some ideal self. At the same time, they are effective enough to rise above the level of mundane tasks. I especially like these three ideas:

4. Intentionally seek professional development

This is good for my job because it keeps my skills sharp and up to date. And it’s good for me because it lets me check whether I like and care about where I’m going.

6. Don’t be a lurker or a slug

By all means, stick your neck out! Do it in a responsible and respectful manner, but do it. It is called technical communication after all…

7. Volunteer and be broad in your scope

Anytime you volunteer, someone’s bound to learn something! And once you’ve volunteered for a bit, you’ve learned enough so you can avoid the topics that are too broad for you… 🙂

– Now, go over to Steve’s post and read it, if you haven’t already… 🙂