DEV Community

Verena Ermes for FINN

Posted on • Originally published at finn-auto.github.io

User Centric Technical Writing: A conversation with Kosara Golemshinska on elevating documentation

Documentation can oftentimes come as an afterthought. At FINN, technical writing is set up as docs-as-code approach to be closely aligned with new developments in the Tech teams. But how can you elevate documentation further and ensure that the audiences' needs are served? How do you align priorities and document the most impactful things? We are trying to get answers to these questions and more by sitting down with Kosara Golemshinska, Technical Writer at FINN, who started her tech writing career at FINN and is continuously shaping user-centric documentation.

Hi, Kosara đź‘‹ Thank you for offering to be interviewed. To dive right in, could you explain what your journey into technical writing looked like?

By education, I am a software engineer. As such, I did hear a lot about the importance of documentation, the different types of documentation, and what role it plays in software development. During each semester in my program at university, we worked on a lot of practical projects in small agile teams. I always ended up advocating for documentation, making sure it gets done, and trying to ensure that it was in a proper state. That was sort of the first indication I had that I am really passionate about documentation, managing knowledge, and managing information.

After university, I went into pure engineering roles, and there too, I still ended up advocating for documentation. I saw the impacts that insufficient documentation had on actual software teams firsthand. Especially in my previous role, I looked a lot at test documents. I noticed that the documentation there was in such a format and in such a state that it did more harm than good. That was when I felt ready to make the transition into being a documentarian.

As someone who's always been very interested in the humanities it really made sense to combine both my technical skills and my language and communication skills into one. Luckily, I found the Technical Writer role at FINN. It was a really good place for me to make the transition because of the role’s focus on software documentation. Right up my alley. And yeah, this is how I'm here today.

What is your current view on documentation at FINN?

It is appreciated and needed. I can see that documentation is part of everyone's job. Everyone takes the time to document their knowledge, whether it is on Confluence, Slack, or in a document that they share with others. The idea that documentation should not only record knowledge but also help generate it is widespread. Documentation is used to brainstorm and to align on the next steps before diving into the details. I think this wide recognition is why we have a very diverse ecosystem of documentation.

At the same time, I also see the effort that people put in to maintain their own documentation. They assign a DRI when they create something and this is the person who's going to follow up. They also try to maintain some sort of standardization in their teams, which is really cool to see.

The documentation is as diverse as the teams themselves. There are so many different types of information being created. And it really depends on the roles and the functions that people have. Documentation at FINN is a living breathing creature.

How do you value the impact of technical writing on our products?

At FINN, we view it as an enabling function since the documentation that technical writing is involved in is entirely internal. If we take our API developer portal as an example, it's an excellent resource that is used not just by the engineering teams but also by the product managers and some business roles to understand how to use our APIs. They hold each other accountable whenever they see issues or need clarification. The responsible team that owns that API goes in and updates the documentation. They see the value in it.

That makes documentation a part of the API landscape. The APIs are essential for how we do business at FINN. But that doesn’t apply to just API documentation. We also have pretty extensive business-related documentation, that is often referenced to align on how things should be done. And it's especially critical in our daily operations. For instance, in Finance, where the stakes are always high, documentation is an integral part of how we operate and what our source of truth is. Because if we can't agree on the truth, we can’t do anything. Documentation serves precisely as this source of truth, for all teams.

You have been studying the book The Product is Docs. What are your key takeaways?

I think it's a very good resource. It's not just an introduction but it also has a lot of advanced topics for all sorts of roles. Any documentarian is going to tell you that we do some writing but that's not the majority of our tasks. We do a lot of research, communication, editing, reviewing, and verifying information. That book, The Product is Docs, focuses precisely on all the processes surrounding documentation. It provides practical advice, for example on the process for defining a learning objective or how to communicate with product managers. It focuses heavily on the processes of technical writing and information development. This makes it really valuable to me and I often use it as a reference. I always find something new in it because there's so much practical advice given, which makes it a mainstay at my desk.

Looking at the research aspects of technical writing, how do you perceive the value of leaning into the profile of a User Experience (UX) researcher?

I think there's a lot of overlap. The fields of UX writing, content design, and technical writing you can also call information development and knowledge management. All of these topics are closely connected as their main focus is managing knowledge. They also rely heavily on empathizing with users, doing user research, communicating with lots of different functions, and using common patterns to manage our content and to make things accessible for users. So, I think you can't really do technical writing at an advanced level if you aren't familiar with UX research practices. The main idea is to understand the users, to understand their needs, and to understand how to provide the most value to them. That's what technical writing is really all about.

How do you imagine an ideal rhythm of technical documentation throughout FINN?

It has to be a very scalable way of doing documentation, because FINN is a very fast-growing company. We defined our own documentation strategy to best match the mission of FINN and to best support our stakeholders. We looked at who our main stakeholders are, what their needs are, and how we can support them. Based on that, we defined our mission: to make knowledge a top–tier resource. This is the overarching idea of what technical writing at FINN is all about.

The mission needs to rest on a set of fundamental principles. We defined these as our pillars: documentation should be user-centric, searchable, and accurate. These pillars are the building blocks of our strategy. For each pillar, we defined activities and metrics to track our progress against the strategy. This is how we approached defining a strategy, which was similar to how it was actually done in our data organization at FINN as well. We're trying to be aligned in how we approach these high-level topics.

What is most challenging when putting such a strategy into action?

It’s definitely managing to keep track of and monitor the metrics that we have defined. Documentation is something that is notoriously tricky to measure. It's not impossible, it's just not straightforward. You need to combine a lot of different things. You need to look at different sources and always view the metrics in context which makes documentation measurement kind of special.

It's definitely a learning experience and I'm curious to see what we will learn from the impact of our metrics. Maybe the impact is going to show us that some of the metrics are not the best choice. Maybe we will see that we need a different approach or we’ll see something new about our stakeholders and their use cases.

Speaking of stakeholders, how do you currently ensure that you are aligned with your stakeholders?

The main thing is communication. The wider field of documentation is often described as technical communication and I think that's a really good way of putting it. So, technical writing is all about maintaining open communication channels and being in a constant feedback loop with pretty much everyone.

We have not just regular meetings that we attend as technical writers but we also have one-on-ones where we try to dive deeper into current challenges and goals of individual stakeholders. We apply UX research and look at specific pieces of documentation and assess how usable they are. We also apply principles from information architecture to make the documentation better organized and, overall, more accessible. Essentially, we apply a lot of different techniques to make sure that we understand what we're supposed to be documenting. We always aim to put our efforts where they create the most impact. In short, the answer is communication, communication, communication.

Thank you very much for sharing your insights into technical writing at FINN. What advice would you give someone who wants to start a career in technical writing?

My first advice is to connect with the very strong technical writing community. There are lots of groups, for instance on LinkedIn or the Write the Docs community. You can find many conferences, too. Look up some meetups and enjoy them. People are really open to newcomers and always happy to share their learnings.

My second advice is to decide on a specific technical writing profile that you want to pursue. There are many avenues for technical writers. Decide on the type of tech stack you want to learn and the type of industry that you want to go in, then focus on that. That's really going to have the most impact.

How do you approach technical writing in your organization? Share your insights in the comments below

Top comments (0)