Jo Stichbury

Technical writer

Ignorance is not bliss

What it’s like to be a new hire. Over and over again.

They stare at your shoes (Image by Tosa Vlad — CC0)

Last year, I wrote a piece about the perils of freelancing. I was irritated by recruiters that initiated enthusiastic conversations, only to disappear half way through an email exchange because they’d found someone who was better suited to the role, or cheaper, or able to commute further. I flourished my badge of disrepected honour and appealed for greater politeness.

Later that month, I met a pleasant recruiter who found me a part-time writing contract. I’m not going to name and shame the client, but I want to use my experience in that role to share another cautionary tale. Although the details are quite specific to my role as a technical writer, sadly, I suspect many people will relate to the general theme of being treated like the village idiot because you are a new hire and know less than anyone else on the team.

I’ll come back to why I think that’s a problem later. First, I’ll explain what happened to me by backing up a little…

What do technical writers in the software industry do?

Technical writers work alongside a software development team to document what they are building. Sometimes they create internal documentation but I mostly write public documentation to explain how to use a product. My typical audience is external, third-party, developers who will use the code. For example, the team could be writing a gaming platform and need documented examples to show external game developers how to use it. Or they could be building a new database and need tutorials to explain it. Software developers are smart people who are used to working without a comprehensive manual, but they usually need basic information and some examples, and that’s where public developer documentation is useful, and why technical writers like me get hired.

But why do software teams need technical writers to create that documentation? Can’t they write it themselves? Well, they do sometimes. But if they are working to a deadline, and most teams are, it doesn’t make sense to take one of the developers away from coding to write a “Get Started” guide or knock up a “Hello World” example. Not only are the developers busy, but they may be unwilling to write documentation: it’s not the most exciting part of the software process. Some are also uncertain of their writing skills, and a number struggle to appreciate the needs of the audience for the documentation. That is understandable — a developer who has worked on a product almost certainly makes assumptions about what others know about it.

Why use temporary writers?

Having a separate, technical writer who is fresh to the team helps because they are neutral. Among the first to try out the product, they find out where a typical user will stumble, and write down what a novice needs to know to solve common problems. As their skills with the product increase, they write the more advanced guides, until there is a spectrum of documentation available. Then they move on to a new contract, handing over the documentation to the development team (or the community, if it’s open source) once it is in good shape.

This approach works well for startups that may not have had much experience in developer community building. The writer brings that with them, and can guide the team about the best channels to communicate, the processes that other teams have found helpful for keeping documentation updated, and the kinds of materials that are popular. They bring a different set of skills at the time they are needed, and then move on.

I should add that there are plenty of technical writers who stay in a particular company permanently and are just as familar with every nuance of the code as those that are developing and testing it. This usually happens in larger companies with a broad product base. But, in short, for a number of smaller projects, it’s useful to have a temporary extra pair of hands to take responsibility for the quantity, and quality, of the documentation.

Meet the new hire

From the writer’s perspective, it’s great to have some flexibility of when you work, with whom, and for how long. It’s also good to have the opportunity of learning about new things, working with different people and, often, with startups doing amazing things.

The essence of the work, as I’ve described above, is that you join a team bringing your experience in written communication, but little or no knowledge of their specialist area. You know how to code, you have a good general understanding of technology and you probably know something about their general area. But the team’s product is — usually — a complete unknown. You go into the team knowing nothing, and are there to ask the questions that their users will be asking, to get the answers, and communicate it all clearly so the development team don’t turn into a support team once the product is released.

Who likes being a noob?

When I start on a new project, I usually make a lot of mistakes in the early days, ask a heap of questions and feel a bit dense. Not only am I getting up to speed with the product, but I am the office newbie, unfamiliar with the people and the work environment, their preferred software tools and processes.

How many people can say they like being a new hire? The first few days include learning the code and scanning the existing documentation, getting set up and working out how to fix things when you break them. There are also soft-skills to learn: such things as temperamental toilets, unfamiliar coffee machines and obscure task planning software.

Then there are the people. I’m introverted and also have a problem remembering faces and names, so I need to meet someone a few times before I’m comfortable. If I’m going to do my job well, I need to be able to build rapport with the development team, so I can bother them with daft-sounding questions, ask them to review my example code and give feedback on the documentation when I’ve written it. I’ve been a developer myself, so understand how much focus is needed. I get that interruptions are unhelpful, and questions about code you wrote 4 months ago are unwelcome. And software developers aren’t always the most communicative of people. You know the old joke?

Q: How can you tell an extrovert programmer from an introvert programmer?
A: The extrovert programmer looks at YOUR shoes while he’s talking to you.

If I’m lucky, when I turn up on-site, there will be some level of documentation available to help me get set up and bootstrap into understanding it before I need to ask anyone for help. But even if it is up-to-date (it usually isn’t) it won’t be enough to form a comprehensive Setup Tutorial or Hello World example. The only way to get write complete and correct product documentation is to talk to the people that wrote the product.

That is where the problems start if you are dealing with people who fail to understand the value of questions.

Don’t think I don’t see the eye-rolls or the sighs. That dumb woman again, why doesn’t she understand our brilliant product? Why is she asking me questions all the time? Why do I have to spend time reviewing her documentation? Why is her example code so trivial?

A plea…actually, a number of pleas.

Fellow colleagues, this comes from the hearts of all the new hires in your team, not just me, the temporary technical writer.

It’s for anyone who has ever started learning something new that isn’t written down yet, and feels nervous about asking the experts.

It’s for those who feel like imposters.

It’s also for any woman who has been talked down to in the tech industry.

  1. If your colleague asks you something that you think is so so obvious: be kind. Be polite. Be helpful. Be respectful. They probably think it’s a dumb question too, but have no other way of finding out the answer.
  2. If you are asked to help, don’t sigh and say you’ll do it later, then “forget”. Yes, you’re busy. But they want to do their job too, and you are blocking them.
  3. If someone books a meeting with you to ask questions, please accept it or suggest a new time and date. When the time for the meeting comes, turn up — ideally on time — and communicate nicely (see points above).
  4. If your experienced-in-life, but inexperienced-in-your-very-specific-subject, colleague sends you an email, please acknowledge it, even if you can’t answer immediately. Give them a timeline when you can answer, if it’s not within a day or so. Don’t hit delete because you are “too busy”. Ghosting a colleague is disrespectful. Especially if you do it repeatedly.
Nobody deserves to be made to feel stupid, worthless or invisible because they know less than you and ask questions.

Why is this a problem?

Most companies will deal with open rudeness or aggressive behaviour, if only to protect themselves. Those that tolerate covert rudeness where staff are ignored or treated poorly for asking for help need to wake up to its impact. Besides slowing down progress on your project, you block your colleagues from achieving their potential, and you damage their confidence and belief in themselves in the future. There’s nothing more important to learning than being able to ask questions and make mistakes. If you feel actively discouraged from that, you shut down and stop learning.

You will not retain unhappy employees, and the people you keep will thus tend to be the perpetrators of this bad behaviour. After time, it effectively becomes part of your company’s identity and values. Do you want your organisation to be open to questions, to new ideas, to discussion about assumed knowledge? Do you want to be able to hire and retain new team members with a range of background and experience? Fix your company culture to allow your new hires to flourish.

On a positive note, I was encouraged to see this tweet from Steve Kinney last week — this is a great description.

What do you think?

Hit me up in the comments? Have you experienced open hostility, rudeness or been ghosted by a colleague when you were a no-nothing new hire?

What’s your worst first-day experience? Please leave a response below!

More by Jo Stichbury

Topics of interest

More Related Stories