One year ago I was starting a new position at DigitalOcean as technical writer. I’m now back to software engineering, but my experience as a technical writer was really rewarding. Here’s some of what I learned in this period, and a few tips that helped me get better at technical writing.

Those who know me for a couple years will probably also know that I started working for DigitalOcean as a developer advocate, creating a “bridge” between the company and the PHP community, given my involvement with this particular community. As I always like to emphasize, being part of the PHP community really changed my career, and while I was back in Brazil I could never imagine the wonderful opportunities that would come my way one day. Joining DigitalOcean was one of these unique opportunities.

One year ago the community team at DigitalOcean went through some changes, and that was when I moved to a technical writing position. I’ve always enjoyed writing, and I felt I was ready to try something different, specially something that didn’t require that much travelling. But boy, was I scared.

There’s a huge difference from writing blog posts and informal things to actually being paid to write more formal content. As a non-native English speaker, I realized that would not be an easy change, and I would have to go way out of my comfort zone to get this right. By the other hand, since I always enjoyed writing in general, this change would push me to improve my writing and learn tons of new things.

TL;DR: Writing is Hard

Writing is hard. The first challenge is to organize your ideas in a way that makes sense, in a way that flows well for the reader. Then, there’s the syntax, the rules, all the language specific things plus the best practices and things to avoid. On top of all that, and more specific to writing technical documentation, there’s the undervalued trait of making it simple and accessible. You can’t make many assumptions about the reader; good documentation should not skip steps assuming they will just figure it out. There are few things more frustrating than following incomplete guides and get stuck at some point because the author forgot to include a few steps.

Writing documentation requires a good deal of empathy. I once watched a talk where the speaker demonstrated that experts are usually less than ideal mentors for beginners, because they have a really hard time to place themselves in the shoes of a newbie. It’s somehow similar to imagining how someone could live without cellphones and Internet, in the past. You are so used to this scenario that it is hard to wrap your head around the idea.

In terms of writing documentation, I believe that it’s really hard for an expert to write documentation that is clear and cover everything that is really important for someone to get started with a technology or a tool.

That being said, don’t feel like you have to be an expert on something to be able to write about it, or even present a talk about it. I learned a lot of new subjects while working as a technical writer at DO, because we are not supposed to know everything; the process of writing a tutorial involves researching, testing and listing all the steps (all commands used to install something, for instance) and only after that you can proceed to the actual writing part.

Sometimes, when assigned to write about a challenging topic that I was not familiar with, I felt scared; however, if someone made it work before, you can certainly do the same 😉 once you have it working, the challenge is to split the process you used into smaller steps, and if possible, simplify a few things. After having it done, it’s essential that you test the whole guide to make sure you didn’t forget a step along the way.

The Heart Wants What it Wants

I have learned a lot in this past year as a technical writer. It was a great experience, and I’m certain that it greatly helped my career. However, the heart wants what it wants; I’m a developer, I can’t fool myself on that matter. Programming is what makes me really excited, keeping me awake at night sometimes, thinking on how I can solve a particular challenge. When I see myself in the future, I’m a developer. I like writing, don’t get me wrong, but developing is what brought me here in the first place, and it’s what I love to do.

I’m extremely grateful for all the opportunities I’m having at DigitalOcean, and I’m really happy they were so kind to help me transition to a software engineer position, even though I had no previous experience with the technologies they are currently using. I am now in a new challenge in my career, even though it’s scary I’m excited about everything I’m learning and, most of all, I’m happy to be coding again after so long. I feel proud of my new job title as software engineer because I fit, I belong here. It feels great to be back 🙂

A Few Tips for Good Technical Writing

Everybody loves lists and actionable items, so here is a list with some things that helped me get better at my technical writing:

  • Use a text editor with spell checking
  • Don’t make assumptions about your audience; if there are any requirements, make them explicit at the very beginning of your guide
  • Nothing is “obvious”, all steps should be included
  • Read out loud what you wrote, as you were explaining to an audience. Is it clear enough?
  • Make good use of headers and subheaders to organize your guide
  • Use formatting to differentiate commands, project names, parameters, etc.
  • Use syntax highlighting for code. If it’s a lot of code, consider using a public Github repository or a Gist, and maybe show only part of the code in the documentation
  • Get feedback from someone who is not familiar with the tool or technology, to make sure it is clear enough
  • Always test what you wrote, step-by-step, after finished. Make sure to test with the same conditions a beginner is supposed to (maybe use virtual machines of a VPS for that)
  • For English writing: this book is excellent, cheap, and small. It contains the most important things you need to know to avoid bad habits and adopt best practices in English writing. When in doubt about a word or when you want to replace it with a better one, use Thesaurus

And, by the way, DigitalOcean is hiring new technical writers! If you are interested, apply at https://www.digitalocean.com/company/careers/ 🙂