The Hows and Whys of writing technical documentation

Deploy
Néda El Hadj-Mimoune
7 min read

Picture this: you know nothing about technical documentation or even tech in general and you decide to pursue a career in technical writing. That’s where I found myself a year ago when I joined Scaleway’s Product Documentation team as an apprentice. Spoiler alert: it was a hell of a ride!

Some people choose to be doctors, lawyers or teachers. These are jobs that are easy to explain because everybody knows what a doctor does. I wish I could say the same about tech writers because everyone’s probably wondering “what the hell is technical writing?” right now. The truth is, none of us knew what we were getting into either.

First of all, how do you break into tech writing?

In Scaleway’s documentation team, not everyone comes from the same background but you know what they say: all roads lead to Rome!

I asked Scaleway tech writers how they ended up writing technical documentation for a living and here’s what they had to say:

Teacher turned tech writer

I used to be an English teacher and my favorite part of the job was making worksheets and support materials to explain things to students. I always had an interest in IT so after 10 years of teaching, I decided to pursue something more IT-oriented and did a Master’s degree in IT. I eventually applied to be a technical writer because it was the perfect combination of tech and pedagogy and let me work with other humans as part of a team.

Linguist at heart meets tech writing

"I initially wanted to be a translator because I had an affinity for languages. During my Master's degree, I studied languages and technical writing as a core curriculum. Surprisingly, it made me want to specialize in tech writing. I'm naturally a curious person so I was tech-savvy but I had no significant experience in IT. I found technical writing more interesting than translation because it allowed me to learn how to use IT tools and softwares, to keep practicing English and to learn technical jargon. Today I have nearly 10 years of experience in tech writing and I still enjoy every single aspect of it."

A lucky encounter

I became a tech writer by chance. I was working in customer service and sales at Scaleway and I knew I wanted to take a leap into something more creative. I was talking about technical writing with another tech writer, and our conversation got me curious about tech writing. An opportunity came up and I decided to try it out. I wasn’t the most tech-savvy person but I filled the gaps by taking courses and self-learning. I also did a course about tech writing so I learned in practice.

From technical support to technical writing

I was always passionate about IT, tech and helping people understand stuff so I became a support technician. I was working on technical documentation but I wasn’t labeled as a technical writer. I didn’t even know that technical writing was a thing. Eventually, I became a technical writer in the same company. I like documentation because it is complete and you can send it to clients instead of explaining everything over the phone and going back and forth.

The takeaway from all these answers is that there isn’t one and only way to become a technical writer. If you are curious and passionate you already have what it takes to take the first step. Of course, like in any profession, there are some skills you need.

So, what the hell does a technical writer do?

Long story short, tech writers write technical documentation to help users use a product or a feature.

Short story long, technical writing is just the tip of the iceberg. You would be surprised to find out just how many hats we wear.

The tasks of a technical writer may vary according to the industry we work in, the size of our team or how many products we have to document. But at the end of the day, the main goal is the same: helping users understand a concept and how a certain product or a piece of software works, when they don’t necessarily have the technical knowledge required to understand on their own.

What a tech writer who doesn’t know anything about a product should do first and foremost, is research the product they are writing about. And if there’s one specific trait a tech writer should have, it is curiosity.

It’s also a collaborative job: we communicate a lot with other teams involved in the product and within the tech writers team.

At Scaleway, our golden rule is: always ask questions, even if you think your question is stupid, even if you ask the same question over and over again because you haven’t properly grasped the hows and whys of a product. You can also use and play with the product yourself to understand it better and get used to it.

"There’s no such thing as a stupid question!", that’s what my colleague Rowena wisely told me.

Once you have enough knowledge of the product, you should regularly touch base with someone who knows the product to check your understanding and get any help necessary with the more complicated ins and outs. You can then start writing the documentation and get feedback from the experts.

The review process is also a very important part of writing documentation so you need to have your work reviewed and/or corrected by other people in case there are some things you missed. Once everything is validated, we publish the documentation and we make sure to maintain it so it stays up-to-date.

But what happens when you have to write documentation for a product you don’t understand?

Have you ever wondered something along the lines of “how do you know what to write?” or “what’s the process of finding out how a product works?”. Sometimes you get really good specs from developers and people working on the products and sometimes you have to figure it out alone. And in these cases, what I do is assume that I know nothing and I start from the basics.

Nobody expects you to be an expert because you can’t possibly know everything about the products. As Marie-Astrid, a fellow Scaler who works in Product Design at Scaleway mentioned in her article on how to design a product you understand nothing about, no one understands everything 100%.

What we tend to do is research on our own beforehand: we watch videos about the subject we’re writing about and read existing documentation online. This gives us a general idea of what to expect.

The great thing about working at Scaleway is we have access to the console which is the graphical interface where we can create the products. We can actually test the process we’re documenting ourselves, and make sure everything works. As previously mentioned, you should not be afraid if it seems intimidating or you can’t work it out straight away: you need to be comfortable with asking questions in order to do your work properly.

Taking initiative and going after the information you need proactively is a must because stakeholders don’t always know what kind of information you need.

Welcoming criticism and feedback is also a big part of the job, because you're not always gonna know everything so you need other people to review what you wrote. Sometimes you have to write documentation last minute so you don’t always have time to research and it is good to have feedback to make sure your documentation is the best it can be despite the time constraints.

I'm a big believer in trial and error, it’s my favorite way to learn.” - Rowena Jones, Technical Writer at Scaleway.

Okay, it’s your turn now!

We believe that our users can bring valuable knowledge by contributing themselves to Scaleway documentation. You can write tutorials that you think could be useful for Scaleway users, and get them published on our documentation site. Tutorials must involve a Scaleway product, and any third-party tools used for the tutorials must be free to use and open-source. You don’t need to use poetic language or write long elaborate phrases, less is more in this case! Are you up for the challenge? Share your technical knowledge and be rewarded for it!

If you don’t want to write the content yourself but still would like to request documentation on our products, you can open a documentation request or bug issue, and specify that you don’t plan on writing the content yourself.

So, are you ready to try your hand at technical writing?

New to Scaleway? Check our documentation website to find out how to create an account and start exploring the cloud!

Share on
Other articles about:

Recommended articles