Meet Anna, the documentation team lead for IntelliJ IDEA

Kristyna Mazankova

Anna is a technical writers’ team lead at JetBrains. In this interview, she let me look under the hood of our technical writing. Online documentation is one of the pillars of our connection with developers, and Anna is dedicated to making it even better and more user-friendly.

Q: Anna, how long have you been working for JetBrains? What background do technical writers normally have?

I’ve been with JetBrains for three and a half years.

Though any company that produces software products has technical writers in their staff, in Russia you still cannot get a degree as a technical writer. So most of the training takes place on the job and relies on experience and self-education. In my team, there’s a combination of people with a technical background and excellent English skills, and people who have a language degree, like myself.

Q: So have you worked in IT since the beginning of your career?

As a student, I took a job in a company called PROMT that is widely known as translate.ru. I wrote linguistic algorithms for machine translation from German into English, and this was one of the most interesting things I’ve ever done. It was really exciting to parse down a language into patterns that you could formalize and feed to a machine translation tool. So, yes, my first job was actually in IT.

Then I taught English to adults for several years, and ended up as a corporate teacher in Borland. Funnily enough, some of my colleagues here at JetBrains used to be my students back then. When Borland closed down, I was determined to stay in IT, so I took  my first job as a technical writer in a huge company called EMC – now acquired by Dell – that sells data storage. I had no experience in technical writing then, and my boss gave me a paper book about good technical writing that was several inches thick! However, all the new tasks I had to accomplish and getting to know the technology was overwhelming, so I didn’t have a chance to open this book until a few years later, when I realized I’d already figured out most things for myself.

Q: Why did you decide to take a job at JetBrains?

Actually, I had wanted to join JetBrains for many years. I even had an interview for TeamCity 7 years ago, but my skills did not prove sufficient back then. My previous job was more about development than anything I had done before, and it provided me with some essential skills, so here I am now.

The main reason – apart from the fact several people I knew were already working for JetBrains and kept telling me what a great company it was – was that I was getting bored with doing things that I already could do well. It did not require much effort on my side, and there wasn’t much room for development. And, as scientists tell us, you have to train your brain, just like you train your muscles, or it starts to decay.

Q: How is technical writing for JetBrains different from other companies?

In many companies, unfortunately, documentation is still written merely because products are supposed to be delivered to customers with documentation. No one really stops and thinks why they write it, who they write it for, and what business problems it solves. And your job can’t be rewarding if you go to work every day and do something that you know doesn’t make the world a better place.

Here, at JetBrains, we want to make a difference. Everyone is so passionate about what they do, and the company is customer-facing, so you always have a chance to speak to your users directly and find out if you are doing the right thing.

Q: Many people have a very vague idea of what a technical writing job is. Can you lift the veil and tell us a bit about your daily routines?

Ha-ha, you’re right. I’ve given up explaining what technical writing is to my friends who are not in IT. My husband prefers to omit the “technical” part and proudly tells everyone his wife is a writer!

Technical writing is an engineering job just like any other job in IT. It’s not only about creating content – it’s also about designing information flows. If you have written quality content and your users can’t access it, what’s the use of it anyway? You might just as well have not written it at all.

Every day we ask ourselves questions like,

• “How will our readers land on our help pages?”
• “How will they read them? Will they just scan through, or read A to Z?”
• “How do readers navigate around our web help?”
• “What questions do our users most frequently ask related to a certain feature or technology?”
• “How do we design our documentation so that it answers these questions and users are not forced to wade through tons of information they don’t really need?”

To help us answer these questions, we employ a number of tools and information sources.

I’m subscribed to a dozen tags on StackOverflow, and my everyday morning routine is going through notification emails from StackOverflow and checking out which problems our users encounter when performing specific tasks with our product. So when I start writing about a certain topic, I already have an idea on how exactly my documentation should help our users and what issues and scenarios it should cover.

Actually, before we start writing anything big, we spend a long time making up a list of use-cases and scenarios, which are then translated into the document structure. We’ve been following this process for some time now, and this seems to be the only way to ensure our documentation is not written simply for the sake of documenting whatever functionality our products have.

Q: How do you measure your success?

We get input from our support team, as well as from a feedback widget that we are redesigning at the moment to be able to get some measurable data on whether our content was useful to our readers.

We are also trying to employ different tools to measure our success and verify if the new approaches we are applying are viable. For example, we can use Google Analytics to check if changing a document structure helps it rank higher in Google search results.   

We are learning to write for SEO – and this is a fascinating new world for us. Isn’t it amazing that by knowing how search engines index content, you can use tricks to make it more discoverable?

Q: Is it difficult to learn the technical stuff?

This is one of the biggest challenges in my job. I’m not a programmer, but I write for developers, so of course I need to have some expertise in the areas I write about. Our product (IntelliJ IDEA) is very big, and of course, you cannot be an expert in every framework or technology it supports. Each writer in my team covers a certain set of features and technologies, and sometimes you need to spend awhile to understand it and to play with it.

Q: Do you find yourself thinking about different projects?

There are a few things that I’d like to get deeper into, for example designing interfaces and user experience. I have some superficial experience in this, and we actually work together with our UX architects to improve our product interfaces and rewritie UI texts, to help users perform their tasks without wondering what each option or action means.

I’d also like to write marketing materials and participate in promoting our products in the developer community. But at present, I’ve already got enough challenging and interesting tasks on my list that will keep me busy for quite a while.

Q: How is your team organized? Is there anything that surprised you at the beginning?

We are part of the development team and participate in daily dev meetings to stay tuned to what’s going on.

At my previous company, I had to fill out a huge Excel spreadsheet at the beginning of each release cycle with all the requirements broken down into atomic tasks, all risks listed, all sign-offs, etc. We could not release anything before finishing all these tasks. To make a change in the initial plan, you had to get half a dozen approvals.

On the IntelliJ IDEA team, it’s all much more agile and flexible. You don’t have bosses who pass down a plan to you and tell you what to do. So we, writers, have to keep our ears to the ground and extract information from a variety of sources to make sure we don’t miss any notable changes and new features.

Q: Where do you see your biggest challenge coming from?

Right now this would be a major reworking of our help system. We are moving away from a reference-based model; we want to focus more on specific tasks that users perform with our products, and on how they can become more productive when using them. Since the existing documentation is huge, this is not something you can accomplish quickly. So, with the routine maintenance tasks constantly piling up,  the biggest challenge for me is to bring this project to completion and not let it become a never-ending quest.

Q: Based on what you’ve said, I suppose you don’t have time for anything else apart from your job, do you?

Work-life balance is not my strongest part, indeed. But I have a little son who will turn 2 soon, and of course, I try to spend some time with my family. It’s great that at JetBrains you can work flexible hours, and that lets me take my son to a swimming pool, or to the playground a couple of times a week.

Last year I also got involved in floral design and making door wreaths, and I really love this. I only have time to practice at the weekends, so I have a few dozens of ideas that will have to wait before they come to life. I really hope I’ll find some time before Christmas 2018 to decorate our JetBrains office with a huge festive Christmas wreath.

Q: Can you think of three words that come to your mind when I say “JetBrains”?

Freedom – that’s something I value very much. To me it does not mean “chaos.” Freedom is a chance to try things out, learn new stuff, make mistakes and take responsibility. We’ve grown much bigger since I joined the company, but luckily we haven’t turned into a company where you have to go through a number of formal steps and approvals to implement something you think is right for your job.

Drive – this is not just a motto for me. Everyone at JetBrains is passionate about what they do. I think our recruiters are doing an amazing job finding people who are enthusiastic and who want to do cool stuff.

Respect – working at JetBrains, I feel that the company respects me and takes care of all its people. These may be big things like good medical insurance, or tiny things like my favorite chocolates or an adorable design for coffee cups. But all together, these things make me feel happy at work.