From SME to tech writer in 7 steps

My colleague Mattias Sander writes today’s guest post about his journey from an SME to a tech writer – which is a noteworthy answer to my post two weeks ago why not to hire an SME for documentation. I thank Mattias for the permission to reprint the post from his own nascent blog The Techwriting Engineer.

---

I work as a professional technical writer even though I am really a subject matter expert. This provides a lot of challenges and opportunities.  Before my current job I couldn’t care less about the uses of en and emdashes, something that has now taken up at least an hour of my life. More importantly I did not have a clue of how to produce quality technical information. What I have is the problem solving skills and natural curiosity of an engineer – willing to analyse and solve any and every problem I run into. I also live by the philosophy that the best way to learn is by doing. The quickest way to learn a new skill is to find someone who already masters that skill and mimic as best you can – naturally taking into consideration that your problems might not be the same as the expert’s – and filtering accordingly.

The first thing I did when starting this job was to find a book on technical writing with good reviews – Developing Quality Technical Information – and then starting to produce my very first user manual. The result left much to ask for – but still had the focus on task orientation – with clarity and concreteness being the most important properties. Choosing this book as my techwriter’s bible was a good choice as it’s easy to use, easy to understand and it’s easy to find what you are looking for in terms of specific topics.

The challenge I now face is how to get a grip on using topic based authoring and structuring content so that it’s easy for my users to find what they are looking for – hopefully making their life a bit easier – because that’s really what user documentation is all about – helping users perform their daily tasks, isn’t it?

The title of this post seems to promise a seven step procedure, so here goes…

To produce quality user documentation – follow these steps:

1. Buy Developing Quality Technical Information and read it from start to finish.
2. Find out who you are writing for and put yourself in their shoes.
3. Research what information would really help them do their jobs (or install their microwave oven).
4. Write down the questions your users need to have answered, write down what task they need to perform and what reference information topics they need to have at hand.
5. Produce the user documentation – using the book as your bible. Make use of the checklists in the appendix for checking the quality of your documentation.
6. Ask SMEs and fellow techwriters to review and edit your documentation – based on different levels of edit.
7. Kick back and enjoy the feeling of having helped Mr Smith install his new microwave oven in time to surprise his wife with a real microwave gourmet dinner.

Advertisement

Top 3 reasons not to hire an SME for documentation

There are 3 reasons (at least) why you should hire a technical communicator for documentation, not a subject-matter expert (SME).

I work in the field of financial software. Applications for banks and other financial institutions are complex. The office swarms with people who have solid financial knowledge, both practical and theoretical.

Recently, I talked to a financial specialist who is writing documentation and his manager about the need for a second writer. Their idea was to hire a financial specialist who could make sense of the pricing formulas and the workflows surrounding the financial instruments.

I disagree. I think they should hire a professional technical communicator, especially since they already have a finance specialist in documentation. If they can find a writer with experience in finance, all the better. Here’s why:

1. Get the full package.

Only a technical communicator will be comfortable with and good at doing all the expected tasks. An SME is ready to explain the instruments and how to trade them. If you’re lucky, the person can also describe them well to users.

But that’s only part of it. The job also includes designing and structuring topics. Editing what other people have written. This takes some hefty experience to do efficiently and well. With an SME, you take the chance to run into a problem with reason number two.

2. Hire for years, not months.

Many SMEs don’t stick around, once documentation gets tough. They may not mind writing documentation, but they don’t think of themselves as technical communicators. So once you expect them to do the “full package”, interest often flags and sooner or later, they find something else to do.

3. Complements beat “more of the same”.

From a corporate perspective it makes sense to hire complementary skills instead of “more of the same”. If there are several financial specialists who can review or even supply domain knowledge they can support the technical communicator. If there is no tech comm person, financial specialists may just scratch their heads over topic types and structured writing – and in the worst case put “crap on a page“.

Your turn

What’s your experience? Do you more reasons why technical communicators should write documentation and SMEs shouldn’t? Do you know counterexamples where SMEs are more helpful than tech comm’ers? Please leave a comment.

Framing tech comm: O’Reilly vs. Dangerfield

Technical communication is perceived in many different ways, some more constructive than others. Luckily, the framing of tech comm is the result of a dialogue/feedback loop, so we can help to shape how we come across.

Tim O’Reilly on the future

Consider Tim O’Reilly, quite a visionary technical communicator. He works to create “The Missing Manual for the Future“. O’Reilly explains it by quoting William Gibson: “The future is here, it is just not evenly distributed yet.” So we technical communicators can help to distribute the future evenly – a pretty noble mission to be on.

Or consider Kathy Sierra whose Kick Ass Curve taught me that my documentation can help users look good and suck less.

– Of course, just because I find cool quotes on the web doesn’t mean my work and I actually help to “distribute the future” (what does that really mean, anyway?) or help a single user suck less. But it’s the attitude that counts. These ideas inspire me. They give me a sense of the best I can aspire to with my documentation.

Rodney Dangerfield on respect

Photo by Jim Accordino, CC-BY-3.0 via Wikimedia Commons

Or consider these assessments:

• “No one reads the documentation.”
• “Nobody cares, but we gotta have it.”
• “This manual is unusable.”

They seem to be rather common, I sometimes even hear them from tech communicators who graduated from RDSP, the “Rodney Dangerfield School of Professions”. The school is named for its patron saint and his motto “I don’t get no respect, I tell ya…“. RDSP graduates tend to accept criticism, when they hear it often enough, not when they find it fundamentally and immutably true.

Actually, it’s worth finding out in a customer survey how many people do read the documentation – and while you’re at it, try to find out how customers use it and what they expect to find it. Maybe only a few care, but if a company cares enough to do documentation at all, they might as well do it right – and yes, you can get documentation done right on the 80/20 rule. And a manual that’s deemed unusable can be made better and clearer.

Tech communicators on their work

Most of the time, my work speaks for itself. But sometimes it cannot stand up against prejudice and misguided judgements. Then it needs my help. I don’t mean making excuses about a late spec or a review that fell through. I mean moving the critic into the position of the generic customer who reads my documentation and finds it useful.

And when I engage with my readers, whether they are colleagues or customers, they are frequently surprised how much thought goes into my documentation. They marvel that

• Documentation that offers less of a narrative is actually easier and faster to use in the majority of cases when customers look up specific questions.
• Many users welcome the separation of concepts and procedures, because they read concepts just once, but need to refer to clear, bare-bones procedures repeatedly.
• What has recently beefed up our marketing material is actually lifted verbatim from the documentation.
• When they find a mistake, I can tell them immediately what I will do to fix it and when it will be rolled out to customers.

This dialogue/feedback loop gives my work the chance to earn respect by virtue of its benefits. And it allows me to follow the goals that O’Reilly and Sierra have inspired in me.

Your turn

What’s your experience? Does it work to enlighten colleagues and customers just how cool your documentation actually is? Does it help? Please leave a comment.

Recommended read: Degree helps tech writers

Here’s an example of how graduates of a tech comm program put their skills to use in a high tech company.

Specifically, National Instruments at Austin contributes two guest posts to the Texas Tech STC Student Chapter blog. Yes, these are recruiting posts, but they do ring true. I think they reflect well how a company can take tech comm seriously and benefit from the formal training and academic skills of graduates. It may be an exception among the employers of tech writers, but it’s an encouraging example. So I recommend these two posts:

Tech Writing…It’s Not Just For Tina Anymore
… asks Texas Tech alumni who now work as tech writers and their managers how they can apply what they’ve learned and what advice they have to students and prospective employees:

• Rayo emphasize task analysis before tool skills – which I’m glad to hear.
• Robin gives SME interviews a reality check that strikes a balance between what’s desirable and what’s possible.
• Heather explains how she determines which documentation formats get produced.

Technical Writing Skills
… has Nathan Stokes list and explain 5 skills which every tech writer can benefit from – especially in this less than obvious combination:

• Editing, including yourself: If you can edit yourself, you’ll be a better writer.
• Productivity, i.e., project management skills to keep yourself organized.
• Enthusiasm
• Curiosity, which can drive you and help you to grow.
• Computer Knowledge

– Previously in these pages, I’ve covered a how a (non-tech comm) degree can help a tech writer.

Your turn

Are these skills useful in the tech writer workplace? Can you learn them – or at least expect to learn them – in a tech comm program? If you have any thoughts or experience, please leave a comment.

Shift your perspective and learn

We tech writers can learn a lot from neighboring disciplines and from people in other professions who address similar issues as we do.

Today, I recommend a couple of recent blog posts that speak to technical writers, too.

For each post, I’ll first point out what it’s about and then explain why I find it relevant for technical communications.

So join me: Let’s shift our perspective and think outside the box for a moment. 🙂

3 Ways Document Collaboration is Becoming More Social

Joe Shepley predicts on CMSWire how writing and maintaining documents will change over the next two years or so. He’s not talking about tech comm documentation, but business documents in general. They will change as social collaboration tools help us flee the “clunky trinity of shared drives, hard drives and email”. In his words:

1. Some documents will no longer be documents at all
2. Some documents will no longer begin their lives as documents
3. Some documents will remain documents throughout their lifecycle, but how they get created and shared will change

– Of course, tech writers have been thinking for years now about formats other than documents, hence the discussions about wikis for documentation and about content strategy. I find Joe’s arguments relevant for these insights:

• Format should follow function. Choose the format that supports your content’s lifespan and frequency of change – and reader inclination, I would add for technical communications. Too often, I’ve had the format dictate how I write: I created Word documents, complete with title pages, table of contents and header and footer layout for internal communications. They would do just as well as wiki pages which are easier to create and modify, but still accountable thanks to history and rollback functions.
• Format can be fluid. The content needs to be reliable throughout the lifecycle, but the format can actually change. Tom Johnson explores this idea in more detail in his recent post Forum → Wiki → Blog Workflow.

Stakeholder interviews for quality content: Why, who, and how

Kathy Hanbury explains on the E3 Content Strategy blog how stakeholder interviews are important as you embark on implementing your content strategy. I’m summarizing those of her points that I find especially worthwhile:

• Interview stakeholders to establish credibility, to identify patterns and structures, and to find discrepancies and gaps
• Interview stakeholders who know the customers, the technology and the subject matter
• When you interview, be respectful of time, carefully craft your questions and take good notes

– For technical writers, interviewing developers or engineers, subject matter experts, as well as customers is an important skill. I appreciate Kathy’s post as a reminder of several points that I sometimes forget:

• Interviews are essential for quality and relevance of the documentation. And nothing can replace them, really, though customer surveys can come close if done well.
• Interviews are about covering all bases. Depending on organizational structure, tech writers have easy access to developers, engineers or whatever department they are assigned to. But documentation has stakeholders in other teams, too, for example in product management, customer service and training. Interviews can help you to ensure that your documentation is useful and balanced by addressing not only how the system works, but also how to use it efficiently and what it was designed to do.

Your turn

To learn more from neighboring disciplines, see my post about “What tech writers can learn from UX designers“.

If you have picked up insights or lessons from other disciplines, feel free to leave comment!

Top 4 steps to solicit perfect documentation reviews

To get the best possible reviews from subject matter experts (SMEs), we tech writers can prepare, make our expectations clear and help our reviewers excel at their job.

Soliciting documentation reviews from SMEs can be tricky: They are usually very busy, juggling dozens of tasks, while putting off several more. The last thing they need is a writer to waltz into their office making a demand on their time. Here’s what I do to get an SME to review a manual of 100 pages or 25,000 words. It doesn’t work always, but it’s worth a try – they are the experts after all… 🙂

1. Preparing

Before I even approach the SME, I prepare:

1. Find the ideal reviewer. This might be a colleague who’s installed and/or used the described product. At any rate, it should be someone who is very close to the customer and knows users’ needs and workflows. I also try to find out why the person is the best reviewer, for example, because of recent or in-depth experience with the product.
2. Get permission to ask. I ask the SME’s manager for permission first. This gives the manager a chance to intervene on the SME’s behalf or to suggest someone else – who’s hopefully as good or better. It also helps to deflect the SME’s attempt to defer me to the manager. But it’s not so I can tell the SME: “But your manager said for you to do it.” – I still have to ask and convince the SME!

2. “Save the date”

I ask the SME well ahead of time if she or he will do the review. I usually approach them in person, but it works as well over the phone or via e-mail. If it’s a talk, I follow up with a “save the date” e-mail as a reminder with the essential details. This contact is mainly about the why and the when, so we discuss the following:

• What to review in general and briefly what the manual is for, why or how it’s new, and what’s to review.
• Why the review is essential, namely to ensure we deliver the best possible product and make it easy and effective to use for our customers – and also for colleagues like the SME. This is a good time to show how our joint effort will benefit the customers and that the SME and I have one and the same goal.
• Why the SME is the best person to do the review.
• When to review and what leeway, if any, I have to accommodate the SME’s schedule.

3. “Please review”

At the ‘saved date’, I send the SME my “please review” e-mail with detailed review instructions. This is mainly about the what and the how, so I include:

• The deadline and to let me know asap if there’s a scheduling problem.
• What to review in detail. Usually, I ask the SME to review the complete manual. But sometimes that’s not necessary: Maybe you have several reviews which complement each other. Or maybe you’ve reused topics that don’t require a review.
• How to review. I’ve found that concise general guidelines work best for non-writers. So I tell SMEs to ensure that the manual is complete, correct and usable, and maybe illustrate each of these criteria with a question.
• How to give feedback. Personally, I don’t insist on any specific format, whether reviewers use tracked changes, comments in the margins or handwritten comments on printouts. But if you prefer on a format, let your reviewer know.

4. “Thank you”

After I’ve received and processed all the feedback, or when the manual has been published, I send a brief “thank you” e-mail to the reviewers. In it, I point out how the reviews improved the manual and what major changes I have made. It shows my reviewers that their input matters, it shows my gratitude, and it leaves a good impression for the next time that I need a review.

This works because…

… SMEs are experts who usually enjoy doing their job well. To benefit most from their expertise, give them a chance to do reviews well. So try to supply all the information and instructions they need.

Your turn

What recipes do you have to solicit reviews? How do you get buy-in from SMEs? Please leave a comment!

Are you asking questions right?

Asking questions right (as in: correctly, appropriately) is more difficult and just as important as asking the right questions.

This is not about asking the right questions – with a little trainning and practice, we tech writers usually know how to do it. I find it much harder to ask the right questions right. I take my cue from Bertrand Russell who (allegedly) said:

The greatest challenge to any thinker is stating the problem in a way that will allow a solution.

(Photograph from Wikipedia.)

I think this is a pertinent issue for technical communicators in several ways:

• It’s our job, essentially. Any customer can state countless questions and problems he or she wants to solve with our product. And any developer or engineer can tell us how the product works. It’s our job to connect the two: To restate the customers’ problems – and to answer them – in a way customers find helpful.
• It helps us get useful answers from developers and engineers. Some of the best developers I’ve worked with always kept me on my toes: They would carefully consider my question and then answer it exactly. On the other hand, they would get easily impatient if I came up with a loose question such as “what is this new feature here?”
• It helps us get constructive feedback from reviewers and SMEs. Asking a reviewer whether “this is good documentation” may not get you very good review comments. For a much better way to state the problem, see Craig Haiss’ post about “Turning document reviews around quickly“. For example, he advises to “clearly indicate any questions that you have for the reviewers”. To allow for an easy and efficient solution, he also recommends  “that reviewers can agree to review deadlines beforehand” and to “use a signoff slip”.
• It helps us get support from management. This is probably the most difficult application of the quote. It requires not so much careful phrasing, but also evaluation and judgment of the problem at hand. This doesn’t mean we do the manager’s job. After all, the quote is not about finding a solution, but about allowing a solution. For example, I once had a scheduling conflict and asked my manager whether we could postpone delivery of one of the manuals. Instead, he negotiated to change one deliverable from a manual to a quick start guide, with a manual to be supplied later.

What strategies do you employ to communicate problems to colleagues and managers? Feel free to leave a comment!