It is 2024, and it is completely normal for a single software product to have users all around the globe, one every continent and (almost) every single country in the world. At the same time, software companies are more distributed than ever, having offices on different continents, but also fully remote employees who can literally be anywhere in the world, as long as they have an Internet connection. This type of diversity affects software documentation as well—not so much in terms of the number of languages used to write or translate documentation into, as English wins that category by a huge margin—but also in terms of who writes documentation. And yes, the person who writes the docs very often isn’t someone who lives in an English-speaking country and is not a native English speaker at all.
Writing software documentation in a language other than your native one comes with an extra set of challenges. First of all, you need to master the language you’ll be writing in, and “master” really means having near-native language skills. This is where one shouldn’t be tricked into thinking that the clear, concise and to-the-point language and style used when writing documentation actually means that you can get away with subpar language skills. It is actually the other way round:
It takes better language skills to write concisely
The hypothesis above is not so difficult to test in practice. Writing quick instructions for something as simple as installing an app on a smartphone, while making sure that it is easy to understand for everyone, doesn’t have long-winded sentences and isn’t overly explanatory, might make you realize that it takes a lot of effort and skill to write something that is brief, but at the same time perfectly informative and meaningful.
What it actually looks like to write documentation in a foreign language?
Being a technical writer for almost ten years, it sometimes feels amazing that everything I have ever written during that time is in English and not a single word is in my native language. To be honest, this has brought me to the point of barely being able to imagine what it would look like to produce any piece of technical writing in my own language and I believe that there are many fellow technical writers around the world who share the same experience. Alas, with the experience cometh the challenges, and they take many different shapes and forms. The sections below present some tips that may help you overcome the challenges of writing documentation in a foreign language.
1. Be confident
Having to write in a foreign language is a serious cause of anxiety and low confidence for many people, even trained linguists. On top of that, when your writing is not just a means of communication, but also the result of your work that’s expected to match the quality of writing done by native speakers, this seriously adds to the pressure and can be a booster to the imposter syndrome. However, it is important to be confident in what you’re doing, and here are a coupe of things to help you gain and maintain confidence:
- You’ve already demonstrated your skills. Even if you’ve just been hired, it is highly likely that you had to present samples of your previous work, or do a test to prove your skills as a technical writer.
- Don’t think native speakers have perfect writing skills. If someone is a native speaker it doesn’t mean that they’re going to have great writing skills in their native language. I’ve seen a lot of below-average writing combined with spelling and grammar mistakes from native speakers, even those who have PhDs. Don’t be anxious because your work is going to be read or reviewed by people who are native speakers.
2. Read
Read other documentation. Either take some great examples such as Stripe, or just read the documentation for a tool that you might be using in your day-to-day work. It makes as much sense to read properly written documentation, as it makes sense to read something that might not be perfect but allows you, as a reader, to notice the imperfections and see what you need to avoid or fix in your own work.
Read documentation style guides. There are loads of them out there. If you haven’t already done so, Microsoft Writing Style Guide and Google developer documentation style guide are good places to start. This doesn’t mean that you have to learn and follow every single rule from the style guides blindly (well, maybe yes if you work for Microsoft or Google), but reading them will likely make you aware of the things you were doing wrong when writing documentation, without even noticing it. As a non-native speaker, you can always make good use of a clear set of instructions and best practices on how to write.
Read anything. Reading just any content in your target language will help your keep the sharpness in your spelling skills, stay aware of different registers, styles, sentence structures, and transformations between them.
3. Use writing tools
No, not ChatGPT. You do the writing, tools help you make it nice and correct by highlighting what you did wrong. Most of the tools might be far from perfect, but spelling and grammar checkers can help you fix the mistakes you failed to notice, especially after reading the same text over and over and no longer being able to spot them. Even if you consider yourself a seasoned technical writer who can take on a spelling bee or a grammar competition in the language that’s not even your native one, there’s always that one misstake that can go unnoticed. And here we go, a nice red dotted line under “misstake” to let you know about it.
While everyone has their weapon of choice when it comes to writing tools, Grammarly seems to be widely used. Tools such as Ludwig can also be really helpful for non-native writers if you want to find or test your sentences in context quickly.
4. Make the best of reviews and feedback
Try to learn as much as you can from the feedback you get. If you work in a team, ask your colleagues to read your documentation. This is the most valuable feedback you are going to get, as your teammates are probably the only people who will pay close attention to how the documentation is written and the linguistic nuances. Other readers will mainly focus on the accuracy of information and usability of documentation, which is also very important, but the language-related feedback is what you can ask and expect from your fellow writers.
