My experience starting as a technical writer

I am a technical writer, and have been for around four years. I work at Roboflow, where I help people learn about computer vision and document various open source software projects we maintain (supervision, Autodistill, Inference, and more).

In this post, I am going to reflect on some of my experience as a technical writer, in the hopes that I can impart some information that is useful to you. This is not a "how to become a technical writer" post, or anything of that nature; there are plenty of other places you can go for that. Instead, I want to speak about technical writing from my viewpoint; from what I have seen, heard, and worked on. I will talk exclusively about software technical writing since that is what I know.

If you want to read some of my work before reading this post, or want some as a reference, here are a few samples:

• What is Zero-Shot Classification? (Explainer)
• DINO-GPT4-V: Use GPT-4V in a Two-Stage Detection Model (Technical tutorial)
• Launch: Advanced Dataset Search Filters, Operators, and Logic (Product announcement)
• How to Use FastViT (Technical tutorial)

Why technical writing?

Think back to when you were last stuck on a coding problem. Really stuck. I will guess that you went to a site like Google, Stack Overflow, or the documentation for the language or package you were using to search for an answer? You might have read a few different pieces of material, then found an answer. Your code works; you can move on to the next challenge.

Technical writers help create that content.

Have you ever encountered a library that you wanted to use but the documentation isn't great? Or the documentation is missing information you need to be productive? Technical writers help ensure that doesn't happen.

As a technical writer, you can help people learn new skills. You get to decide how someone learns a skill. What they should learn first, what path they should take. This is true whether you are writing a tutorial (i.e. how to calculate an image embedding), a piece of reference material (i.e. how to use a library function), or anything else. You get to use your experience to help others have a smooth learning experience.

My motivation as a technical writer stems from being able to help others learn. If I had to explain what I do to someone who doesn't code, I would say one of two things:

1. I write documentation for software companies (this sounds a tad boring, but it is accurate and sometimes this is what I need and I like this description), or;
2. I help people teach computers how to see (I document computer vision software professionally).

That second point, something I came up with earlier this year, brings me a lot of motivation. I build some computer vision technology, but I spend most of my time helping people use what my team has made. I love doing this, and my team enjoys having someone who can take ownership over documentation.

As a technical writer, you will learn a lot. Every day.

Before I started my current job, in which I document computer vision, I didn't know much about computer vision. Now, I can confidently explain what CLIP is and how you can use it to solve various vision problems. I can explain how to identify the colours in a segmentation mask. I can explain how to efficiently filter predictions from state-of-the-art models. I learned almost all of this through my work, with help from my colleagues, a lot of reading, and experimentation.

Mediums of writing

What you do as a technical writer varies depending on for whom you work and what work you are given. Back at the start of my career, I wrote technical tutorials. I had done plenty of writing in my free time, too, although nothing of particular significance. I was learning. I loved words and language. I enjoyed the process of thinking through how to explain a concept.

My first job was to write about Python. I wrote tutorials for beginners, the kind of guide one might read as they are learning the fundamentals of the language. I wrote about what I knew. Nothing was particularly groundbreaking, but I loved the work. I got to think about a topic and explore how I wanted to communicate it. Indeed, a technical writer must be an effective communicator. A communicator who can code well.

When I started to write about technology, I noticed something: a particular interest in documenting how people can use technology, and how I use technology. I wrote more in my spare time, exploring different mediums of writing. I had, up until this point, learned about two different types of technical writing:

• Tutorials, in which I walk through how to accomplish a specific task, and;
• Retrospective blog posts, in which I walk through how I did something, without necessarilly showing exactly how I did it.

The former was professional and the latter was for fun. With every post I wrote, and write, I gained more confidence. I refined my format. My style. The latter became part of how I made side projects. I would write a software project then write about how I made it. The inspiration for this was largely the IndieWeb community, in which members are encouraged to document their projects. Writing about how I did something could start a discussion. In both the aforementioned formats, I could teach someone something new.

In my spare time, I also wrote reference material. For example, I worked on the IndieWeb Utils Python library. This library features many utilities that are useful for building social web applications. In this project, I learned more about software documentation: setting up a documentation tool (in Python), code documentation standards, working with someone else on code documentation, and more. I learn a lot from projects in my spare time.

I have written numerous explainers, too. Explainers are writing in which you define and explain a concept, in depth, potentially without reference to any code. In my mind, explainers often start with "What is?". For example, "what is an image embedding?"

Moving on: Reference material, communication

I moved on to a job in which I was documenting software, referencing what I had previously written as examples of my work. My new role, where I work on the Roboflow marketing team, opened up new worlds of technical writing. Whereas I had previously written tutorials for work and reviews of how I made a project in my free time, I was now empowered to spend more time on examples. Digging deep into a particular subject matter, making an example project, and then writing about how someone could make that same example.

Earlier I mentioned that technical writers need to be effective communicators who can code well. You don't need to be a brilliant coder; your talent can shine through in how you explain concepts. With every tutorial I write, I ask myself "what do I expect someone to be able to do at the end of this guide?" I work backwards in my mind through the steps someone would need to accomplish a goal, then I document those steps. With every piece of reference documentation I write, I ask: will this give someone what they need to use this library?

Knowing your audience

Knowing your audience is essential, a skill you will pick up the more you write and the more you work with others. Professionally, I write guides about computer vision, a field of machine learning that focuses on images. Computer vision is broken down into a few task types, including object detection, classification, and segmentation. Object detection is a method of finding the general location of objects in images. Classification refers to assigning one or more labels from a limited set of categories to an image. Segmentation refers to finding, at the pixel level, the location of objects in images.

Sometimes I write beginner material, like "what is object detection?" In such posts, I know I have to restrict my vocabulary. In all cases, I need to make sure any term I use that someone might not know is defined in my work, but in beginner posts there are many words I know I can't use. In an article like "what is object detection," I want someone to be able to answer that question in their own words by the end of the post; the more jargon I use, the harder that is.

Sometimes I write more advanced material, covering a topic like how to use a new machine learning model. In such a piece, I introduce the topic (the model) and explain, in detail and step-by-step, how someone can use the model. I can assume familiarity with machine learning, so I don't have to define common terms like object detection or classification. But I can't assume familiarity with the model, since someone searching "how to" use a model likely has limited knowledge of that model. It is my job to give people the knowledge they need.

Finding a role

I have found technology startups to be an excellent place to look for technical writing roles. These roles often pair with other repsonsibilities and fall under a marketing team. For example, you might be a "technical marketer" (my job title), with technical writing as one of the ways in which you are going to grow a project. I have worked for two early stage startups as a technical writer. In both roles, I have had a lot of ownership over what I do. In my current role, I have been given excellent support and feedback to help me grow, but this is not always a given. Startups have limited resources; starting out may be uncomfortable unless you have already done some writing in your free time (which is a great idea!). With that said, I have a bias: this is the path I took.

I don't know a lot about larger companies, but I do know that there is always a need for someone who can document software. From the smallest Python package to the largest database solution in the world, documentation is essential.

General tips

Write, a lot. Expect that some of what you write will not be good. I have written many a blog post or tutorial and thought "I don't like this too much." As you write more, you will likely become more "picky". Or, in other words, you are developing a taste. You are learning what you like and what you don't like in writing. A few years in, I can now read a sentence and start picking it apart; this skill is useful when I edit others' work, and do other tasks that aren't necessarily technical writing like copywriting.

Get feedback from a good editor. I often skim through the editorial feedback, having trust in my editor. Some comments from your editor will define your work. Here are some examples from my work of my editor giving a comment that I think about regularly when I produce new content:

• Make one amazing example that you explain throughout your work. Referencing lots of "for example" cases can be confusing.
• Make sure abbreviations are in their full form when you first use them (i.e. "Retrieval Augmented Generation (RAG) is ...", then you can say RAG later on).
• Keep paragraphs to a few sentences.
• Explain exactly what a long code snippet does, step-by-step. This is personal preference, but something I think is valuable. If someone is not comfortable with the code, the text explanation will help them reinforce their knowledge.
• Use simple words where possible. "use" instead of "utilize".
• Be specific about what a given piece of content is going to help someone do. I like to end conclusions with "In this guide, we will..." and list 2-3 things that someone can expect to have done.
• Add example outputs from code. Add visuals where appropriate.

If you don't have a good editor available, experiment with new styles and continue to push yourself. If you are writing a personal blog post, ask a friend for feedback. When I started writing, I wasn't too comfortable with active feedback. The right editor helped me open up through constructive and detailed feedback that never made me feel like I had made a mistake. Building a growth mindset ("how can I make this better?" vs. "what did I do wrong?") has taken a lot of work; it is something I refine every week through the course of my job.

Technical writers: Not just a writer

I mentioned earlier that I am a "technical marketer", which encompasses more than writing. I maintain open source software, contribute to our product, and more. With that said, even if my job was "technical writer" I would still not be writing and editing my work all the time. Being a technical writer involves not just writing, but:

1. Iterating on your guides over time when you receive feedback.
2. Helping team members find your content. For instance, I help our sales and customer success teams find materials that are relevant for prospects and customers, allowing them to be more effective.
3. Assisting with the architecture of documentation. This refers to how pages connect, table of contents structure in your content, and the general flow of pages.
4. Creating documentation infrastructure. This refers to creating mini documentation sites using tools like mkdocs, creating automated actions for generating documentation on GitHub, and all the other little tasks that keep documentation running.
5. Writing tips for your colleagues to help them learn how documentation works at your organization.
6. Coordinate with designers to create visual assets, giving them the explanations they need to do their best work. (Designers are magical -- thank you for all that you do!).

At my work, I actively encourage people from all parts of the business to contribute to our content, whether their contributions are technical writing, product explainers, or anything else that would help a customer or a member of our audience. I help brainstorm ideas, provide feedback, edit content, and more. I love helping people explore writing. Writing a blog post gives a sense of accomplishment. Helping someone get to that feeling is humbling, especially if they don't write too often.

Conclusion

Technical writers are often behind the scenes, working away to help people use tools effectively. As a technical writer, you are tasked with knowing something inside out and distiling that knowledge into material that will help someone learn something new, create something, or solve a problem. With every paragraph, code snippet, and example, you can help someone feel more comfortable with a topic. You can educate, empower.

You do not have to be the best coder in the world. Being able to communicate what you have learned in a way that others understand is your job.

My job is roughly a 30/30/30 balance between coding, writing, and other tasks such as meetings, reviewing content, giving feedback on technical initiatives, and more. With that said, as aforementioned, my job scope is broader than technical writing. This balance works well for me: I don't enjoy coding all day unless I am working on something that really excites me, and even then I cannot sustain that motivation for long periods of time. With technical writing, I can code, document, work with a team, and feel like I can help people.

Bonus: What tools do you use for your writing?

The inspiration for this article was a blog post published on Opensource.net. The initial structure of this post was going to be answering, one-by-one, the questions posited in their post. I decided this would be too constraining. I think I covered most of the questions abouve, though, with one exception: what tools I use?

I use Google Docs for professional writing, Typora for personal writing (and professional writing if I have an unreliable internet connection), and Visual Studio Code for coding. I don't use Grammarly, etc. Over the years I have come to learn what I do and don't like. Every day I learn more about how words interact; software that suggests how words should be structured is not empowering or exciting. I rely on Google Docs to identify typos.

I write best when I have long, uninterrupted periods of time during which to write. I am now accustomed to the occasional piece of writing that needs to be done on a short deadline. This is a muscle I need to build more.

Extra bonus: An anecdote

The term "technical writer" is vague. I met an older man in a San Francisco diner earlier this year. We got chatting; he is a local to the diner. We spoke about everything from travels to our jobs. I noted I was a technical writer, to which he responded that I "write the manuals." The man worked in software. This interpretation has stuck in my head as a humbling reminder of what I do. His words made me feel proud at what I do. I write the manuals, or as I have come to say now, the documentation.

The team on which I work at Roboflow is not hiring at the time I am writing this article. But, we are hiring for other software roles, and may open up more marketing opportunities in the future. Keep tabs on our careers page if you are interested in working with us. If you have a question about technical writing that I did not answer above, email me. Perhaps I can write a blog post to answer your question!