Congratulations! You hired your first technical writer. At some point you must have realized that you needed one, lest your product becomes a user nightmare. Or perhaps you thought that hiring a writer would free your developers from writing documentation and feel more “agile”. Whatever your motivation, you had the courage to hire a documentarian, and for that we applaud you. Now, how can you make sure your tech writer will thrive?

I’ve recently become a docs maintainer for OpenTelemetry, a pretty big open source project. As I often receive questions on how to start contributing to open source docs, this seemed the right time to write about it. Let me tell you how I started and progressed, and what you can do to start your open source documentation journey.

Just around the time I was complaining about the scarcity of books on technical writing, I got a copy of Technical Writing for Software Developers by Chris Chinchilla, a regular of the Write the Docs community. Delighted by the chance of reading a book from one of the sharpest pens in technical writing, I set aside some time to read through the nine chapters and write a review. The book taught me little I didn’t already know – Chris and I use the same tools and methods. The biggest value I extracted from TWfSD is its reflection of the times: it spurred lots of thoughts on the future of our profession and how we promote it.

With the job market getting tougher by the day, there’s a rising belief among tech writers that their role is “too niche” and a “dead-end job”. I think that’s the wrong way of looking at our profession — at any profession. Let me cast aside that dark veil of pessimism and offer an alternative viewpoint, that of tech writing as a platform to other professions, one that lets you move laterally with just a bit of curiosity and courage.

People usually say that I’m a pleasure to work with and that I’ve a highly collaborative spirit. The fact that I’m good at teamwork doesn’t mean that it comes naturally to me. Quite on the contrary, being a good teammate is a skill that I constantly need to train and refine. The following are things I remind myself on a daily basis, à la Dune’s inner monologues, to be a better teammate at work.

Recommending books for technical writers that aren’t old technical manuals is hard. There are very few books on the craft of technical writing, a shortage that I find sharply ironic for a writers’ profession like ours. When I became a tech writer, the books that helped me the most were about other topics that make up the job, like English language, design, and the programmer’s mind. Let me share them with you.

A few days ago I had an interesting conversation on the pros and cons of Markdown for technical documentation with Ed Marsh (Goldman Sachs) and Eric Holscher (Read the Docs) in a webinar hosted by Scott Abel (The Content Wrangler). Here are some of the things I said during the webinar, transcribed and edited for clarity.

A month ago, Lana Novikova asked me to imagine the future of software documentation. What will software technical writing look like in, say, 2049, when our profession will be a century old? Will we be writing markup in git repositories or use ÜberDITA in space? Will our job still exist? I’ve put my futurist hat on to picture the shape of our profession 25 years from now. Buckle up!

Some technical writers in my network are genuinely worried about their professional future in the AI age. Will large language models take my job, they wonder. Are we going to be replaced by GPT, they ask in meetups and community forums. My short answer is “No”. My longer answer is “No, unless you reject the benefits of LLMs”. For my complete answer, keep reading this post.

Soon after publishing Tips for hiring your first technical writer, some readers kindly suggested to follow up with a post covering the previous step in the tech writing journey, that is, the realization that one needs a technical writer. As there seems to be a strong appetite for this kind of content, I’m going to spend some words to list what I think are the most egregious signs that your team, company, or product requires a technical writer (or a tech writing team).