Meet Anna Gasparyan, the documentation team lead for IntelliJ IDEA

Oksana Mandryka

Kristýna Mazánková, PR Manager at JetBrains s. r. o., Czech Republic: “Anna is JetBrains technical writers team lead. In this interview, she let me look under the hood of technical writing. Online documentation is basically 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 in JetBrains? And 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 who know English very well, and people who have a degree in languages 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 that was several inches thick about good technical writing. However, all the new tasks I had to accomplish and getting to know the technology were 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 the job in JetBrains?

Actually, I had wanted to work at JetBrains for many years. I even had an interview for TeamCity 7 years ago, but my skills were not enough 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 reason – apart from the fact that there were several people that I knew working for JetBrains, who 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 atrophies.

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

In many companies, unfortunately, documentation is still written simply 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. And 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 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.

The questions we ask ourselves every day are “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 they navigate in 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 quite a long time making up a list of use-cases and scenarios that 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, and 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 measuring our success and verifying if the new approaches we are applying are viable or not. For example, we can use Google Analytics to check if changing a document structure leads to it being ranked 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 quite a long time 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 on improving our product interfaces and rewriting UI texts to help users perform their tasks without wondering what an option or an action means.

I’d also like to write marketing materials and participate in promoting our products in the developers’ 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 developers’ team and participate in the daily dev meetings to stay tuned to what’s going on.

In the company I came from, I had to fill a huge excel sheet at the beginning of each release cycle with all requirements broken down into atomic tasks, all risks listed, all sign-offs, etc. And you wouldn’t release anything before finishing all these tasks, and to make a change in the initial plan, you would have to get half a dozen approvals.

In 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 it is the major rework of our help system. We are moving away from a reference-based model and want to focus more on specific tasks that users perform with our products, and 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”, it’s the 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 – it’s not just in our motto. Everyone at JetBrains is passionate about what they do. I think our recruiters are doing an amazing job finding the people who are enthusiastic and who want to do cool stuff.

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