Quick writing tip: What’s the default, and why?

As a technical writer, one of the most important questions you can ask yourself is “what are the default values of the choices a user can make, and why”.

For example, if an option is disabled by default, what does that tell you about the average user and their workflow? Are you trying to protect them from a common mistake? Save them an extra step most of them won’t benefit from? What kind of user, under what circumstances, would enable the option? What kind of user, under what circumstances, would want to enable the option and should be strongly warned against it?

Now consider explaining all that to your users. You’ll probably be helping them make the right choice.

I Wonder That You Will Still Be Writing; Nobody Reads You

Agile got (at least) one thing right: stop writing documents no one’s ever going to read. If you want to honestly assess what will or won’t be read – and therefore what should or shouldn’t be written – you should answer some basic questions.

Continue reading “I Wonder That You Will Still Be Writing; Nobody Reads You”

Don’t Let HR Block Your Next Technical Writer

First let me clarify – I’ve nothing against HR and their involvement in the hiring process. What I object to very specifically are two habits: letting HR choose who gets interviewed, and letting HR do the first interview and veto some of the candidates before they ever meet the technical writing team leader.

Continue reading “Don’t Let HR Block Your Next Technical Writer”

Do not Hire This Person: Technical Writers Edition

Three things some technical writers say that should serve as a warning sign that you may not want to hire them:

“I only need to understand it at the UI level”.

If you don’t understand how and why things happen, you’re no better than the user. Anyone can read a field label to understand what goes there.

“I don’t proofread.”

Some writers treat proofreading the way some programmers treat testing – as something lesser people should do. It’s the sign of a delusional ego or an unhelpful team member (or both). Note that this is not the same as saying “I’m really bad at proofreading myself”, which is only a problem for writers working on their own.

“I don’t accept client feedback”.

Another ego problem. Obviously some clients are to be ignored – we’ve all met some who gave utterly useless feedback just because they felt it was their duty to say something. But rejecting all client feedback off-hand is another way of saying “I refuse to learn from my mistakes”.

Do not Hire This Person: QA Edition

Written in collaboration with Efrat Wurzel

Three things some testers say that should serve as a warning sign that you may not want to hire them:

“I can’t understand a feature or start thinking about its tests until I use it”.

Obviously there are some things that will click better when working with the feature. But anyone who says they can’t do anything with a feature until they start working with it – not even with a good design and spec – doesn’t have the imagination and analysing skills for this job.

“I’m not an organised person, I don’t put effort into keeping my tests in order”.

Good luck figuring out what you did and didn’t test, three weeks into a four-week test “sprint”.

“I rely only on developers to understand a feature I’m testing”.

Developers can tell you what the feature does, not what it was intended to do. Testers who don’t understand the gap between these two ideas – and how many different elements go into creating this gap – don’t get how software is developed.

The Doomed Knowledge Transfer: Last Minute, Improvised Show and Tell

Leaving your job and training your replacement? There are four simple rules to effective knowledge transfer: create independence, work together, plan and give yourself the time to do these things.

First and foremost: assume that you will not be available to answer any more questions after you leave. Even if you’re staying in the same company, just in a different role, you need to teach as if you’re joining the mission to Mars. If you create a dependence on yourself by constantly saying “oh, just e-mail me when you need this” you’re going to make life very hard (and unimpressive, from the bosses’ point of view) for yourself and for the person you’re teaching. In a related note, nothing is too trivial for a knowledge transfer. If you know it, your replacement needs to know it.

Don’t do a Show and Tell. Work together: write documents, write code, write tests. You teach much more when working than when explaining some theory in front of a slide show, and seeing how your replacement works will tell you where to put some extra effort.

Plan your work. If you don’t have a plan you’ll jump around, which is both confusing and liable to make you forget whole topics. You also can’t asses times without a plan of what you’re going to cover.

Which brings us to time. You have to be realistic about how long you need to spend on a knowledge transfer; one day is not enough. And don’t forget – there is only so much information a human can pick up in a single day, so if you’re planning a series of twelve hour days – you’re planning to waste half of your time.