The Importance of UX Writing

Back in time, all writers in the company were responsible for reviewing the UI strings. At some point, the department policies changed and we were no longer responsible for doing this. 

However, at the end of 2020, when I started working on the Wavefront project, there was a need to do UI string reviews and suggestions for improving not only the UI text, but also the UX design. Some of the instructions we had were present in the UI and so, it was me who had to review, test and suggest improvements.

Truth is that easy to understand and follow UI, supplemented by meaningful UI strings and error messages can make all of our lives easier. Nobody likes to waste their time and read text which is incorrect with grammar or spelling mistakes or just doesn't make sense. Nobody likes to use apps and products which are not intuitive and require a lot of learning and research or reading hundreds of pages. 

As I like to say "Тechnical writers help users to do their job easily and go home to their families on time without the need to work overtime." 

And it's not only about the user manual or online help.

Good UX writing and microcopy guides users through the product and help them achieve their goals within the product. 

If you don't have a dedicated UX writer or a technical writer who knows the UX writing rules, please hire one! A great writer can help you improve the user experience with great time-to-value, low friction, useful features that actually work, and the best possible customer support.

A generic message such as "A fatal error occurred" can only panic your customers because they lack context. Tell your customers the true error, what stands behind it and offer constructive advice how to avoid it or correct it. 

An example of a bad error message is this NatGeo kids website message: 

Instead of just telling me that I am not eligible for shopping, tell me why can't I use the shop and how old should I be to use it. Probably a message such as:

You can't use the shop, because you're not  "XY" years old.

would sound much better?

Writing Samples

The list of samples on this page covers some of my latest technical writing work. 

These pages and videos are all related to the Tanzu Observability by Wavefront project, which was at some point was renamed to Operations for Applications. Since the product is dynamically changing (it's a SaaS product), the links to the doc pages are links to the versions I have authored and submitted in the Wavefront open-source GitHub documentation repository.

Wavefront is a high-performance streaming analytics platform that supports observability for metrics, counters, histograms, and traces/spans. 

All doc pages published to the documentation website are written in markdown and stored in GitHub. For this particular product, I have also worked on:

• Release notes
• Pendo guides
• Online help
• UI strings

I also redesigned the landing page of the website, managed to implement a Copy button which appears on each code snippet, so that customers can easily copy the sippets and maintained the Java script which we used to pull content from the engineering repository and publish it to the documentation website. 

If you need more samples, I can send more as PDFs.

Tutorials

• Invite New Users from the VMware Cloud Services Console
• AWS Integration Tutorial
• Windows Host Integration Tutorial

Documentation pages

• Using PromQL
• UI Differences Between Original and VMware Cloud Services Subscriptions
• High Cardinality Data
• AWS Integration Overview
• Set Up and Manage an AWS Integration Through the API
• Set Up and Manage a GCP Integration Through the API

Videos

• Search for Content and Save Searches
  Video scenario, screen capture, and voice over audio are done by me. The video is created with Camtasia.
• Send Metrics from a Windows Host
  Video scenario, screen capture, and voice over audio are done by me. The video is created with Camtasia.
• How to Use PromQL
  Video scenario and screen capture are done by me. The video is created with Camtasia. The engineer who was working on the feature did the voice over audio recordings.

My short story

Straight out of University with a masters degree in Chemistry, I found myself in a professional field that I happened to love and enjoy.

This was a profession that had nothing to do with Chemistry, medicine or anything like that… but I loved it so much that when I understood what this profession is actually all about I was proud to say:

I am a technical writer.

I often had to explain to friends and acquaintances what it is and still I did that with passion, and pride because it became a part of me.

As I loved so much what I was doing, I wanted to give more people the chance to become tech writers. So, I started mentoring the new hires on my team and I found out that being a mentor is something which makes me feel fulfilled.

Seeing others grow and in turn fall in love with the profession made me feel happy and proud at the same time.

Dreams change. In real life, they do not end with a happily ever after. As a technical writer, I could mentor 2-3 people in a year. If I wanted to continue to do that at a scale, I had to change my role to that of a manager. Start hiring, build a team. This was a big and very difficult step for me. I still loved technical writing, but I felt the need to do more than that. I had to let others do it while I provided guidance, encouragement, and (I hope so) inspiration. My toughest lessons were stepping back and observing without interfering, delegating and giving advice only when asked.

The greatest gift from my management role was the pure joy of seeing writers on my team grow and excel, but above all it was the feeling that we shared a common passion and go in the same direction.

After several years in management, I realized that I miss writing technical documentation too much, I missed the investigation, the testing of the products, the communication with SMEs, I even tried doing both technical writing and managing people at the same time and this resulted in burnout. So, I stepped back and became an individual contributor again.

Pursued other dreams, obtained a certificate in UX writing, was a part of a wonderful team of software engineers, UX designers, product managers, technical support engineers, and writers.

I often say: I became a technical writer by chance and I fell in love with the profession, and luckily the love is mutual. This is a wonderful journey and I dream that it goes on.

Hi, I am Margarita Staneva - a Sofia-based technical writer with more than 20 years of experience as a technical writer in the software industry.  I started as a technical writer in 2002 when I worked as an expert in a bioinformatics company. Back then, when the company manager asked me to write the user manuals and the online help of the products, I had no idea what technical writing was. I also didn't know that what I was doing was a well-established profession abroad.  I worked in several companies and I grew from senior technical writer, through manager, to senior staff technical writer at VMware. I have experience with project and people management, process establishment and transformation. I have also worked with my team members to create and deliver trainings for technical writers and also for software engineers. I am a proud co-founder and was a regular presenter at the Evolution of Technical Communications (ETC) conference, which is now owned by tekom Europe. This is my blog for showcasing my technical writing experience and helping you get to know me a little. Tell me how I can help you by sending an email to ita.staneva@gmail.com or reach out to me in LinkedIn.