4 benefits of peer editing documentation

Peer editing is the second best thing to hiring a professional editor and brings additional benefits to your tech comm team.

At our company, we technical communicators and some QA analysts all collaborate on Release Notes for our product. It’s a complex financial application, so our Release Notes go to some lengths to explain to customers what exactly is new and how it helps them improve their business and workflows.

Editing and reviewing

This release is the first time I get to work on a language edit for Release Notes topics, together with a colleague who edits, among others, my own topics which I shouldn’t and couldn’t very well edit myself.

Our language edit is one of two editing passes:

• The language edit ensures clear and correct language, including grammar, usage, and style guide compliance, in unambiguous, internationally comprehensible English within each topic.
• The substantive edit, the second pass, focuses on the structural integrity and usefulness of topics as well as the relationship between topics.

Even before the editing passes comes the content review by subject-matter experts who are much better at verifying the actual contents.

I guess the best way to edit is to get a professional editor. Unfortunately, we have neither the time nor the budget to hire one. So I think the second-best way is for technical writers and communicators to peer edit each other’s work. Here are my (overlapping) benefits and reasons why I think peer editing is such a good idea.

The benefits of peer editing

1. Ensure consistency. It’s a great way to improve consistency and common usage among collaborating writers. And it ensures that your style guide works. You really should have a style guide before you peer edit and then use your experiences and findings to fill in the gaps, throw out what you don’t need and change what doesn’t work.

2. Realise growth opportunities. Peer editing is a quick and pretty reliable reality check what each writer does and doesn’t do well, relatively speaking, compared to other writers. And I don’t only mean writing weaknesses. When I first started doing peer edits, I was quite humbled to learn that my criticism wasn’t exactly helping. So I had to figure out how to offer constructive criticism – which I think has made me better and more complete writer. Depending on your team, you may even find that you can teach each other to some degree.

3. Encourage mutual trust. It gives all writers a formal, regular opportunity to check in with each other’s work. It can anchor the good practice to take responsibility for one another’s work – and to learn to listen to others criticize your work. In the best case, it helps colleagues to grow into a team where people trust each other.

4. Enhance group dynamics. If you’ve come to trust each other, you’ll find you collaborate better. Knowing each other’s strengths, you can become more efficient and more productive as  a team, just as members of a sports team knows almost instinctively how the others act.

Your turn

What’s your experience with peer editing? Does it work well? What didn’t work? Feel free to leave a comment.

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.

All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!

Reasons

The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!

Efforts

Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

• Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
• Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
• Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.

Mistakes

Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

• Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
• Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.

Keeping your documentation stakeholders happy

Don’t forget your stakeholders and their practices as you improve and change documentation. – That was the humbling lesson I learned (once again) as I presented our revamped documentation to non-tech comm colleagues.

Reporting on progress

The company I work for currently moves its documentation towards more structured writing and topic-based authoring. We’ve already rolled out redefined processes and several topic-based user manuals, so it was an opportunity to present to  non-tech comm colleagues what we’d done already, why and how we did it, and what else was in store. I talked about topic-based authoring and how it’s chunked, task-oriented, reusable, and independent of delivery format. Then I talked about the benefits and challenges:

• For users, topic-based help can be updated more frequently, it is easier and faster to use online, though it breaks the narrative flow
• For everyone working on our module, it means easier contributions
• For the company, it allows to leverage* content after one-time migration efforts

* I know “leverage” is not a verb, but there were managers present who love the word… 🙂

I thought I was pretty clever for presenting how cool the new documentation was not primarily for writers, but for users, my colleagues and the company as a whole. And it did go over well on the whole. But there was…

The thing about trains

The most contentious issue turned out to be an unexpected use of the documentation: Current user manuals sometimes contain flowing prose walk-throughs of sample setups with many screenshots. When they are written well, they are nice to read. And allegedly users like to print out the PDF files and read them on the commuter train.

The problem of prose

There are several problems with the narrative manuals for users:

• They are hard to use and search in, unless you want to know exactly the one thing they are describing.
• Any sample setup is bound to miss what they need by a little or even a lot, because our product is highly configurable (you can even customize field names in windows).

There are problems for writers as well:

• The prose is really hard to update when functions or processes change because the narrative flow may require small or large changes in several places.
• The screenshots take longer to update and localize than mere text.

I gave these reasons, invited colleagues to check out the manuals done in the new fashion and cited survey findings that most of our users consult the documentation when they have a specific problem, though very few actually read manuals end-to-end.

But the ultimate lesson for me was that I could focus on our mission all I want, I also need to address the change with my stakeholders not only in rational terms, but also in terms of their habits and expectations.

Your turn

Do you think the customer is always right, even if he asks for documentation that is harder to maintain and harder to use in most cases? How can you promote change among stakeholders which you are sure will benefit everyone in the long run? Please leave a comment.