Discussing Markdown and structured content with Niklas Begley

Last week I had the pleasure of conversing with Niklas Begley from Doctave. It was a follow-up to The Pros and Cons of Markdown, focused on why Markdown and other lightweight markup languages could benefit from some structure, in the DITA sense, but without going the XML way. Hint: There could be a bit of JSON schemas involved.

How to set up your tech writer up for success

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?

Contributing to open source docs as a technical writer

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.

Review of Technical Writing for Software Developers

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.

Technical writing is not a dead-end job, it's a landing pad

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.

Things I remind myself when working with others

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.

My favorite books for tech writers

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.

The pros and cons of using Markdown

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.

Technical writing in 2049

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!

What to do when you're feeling AI anxiety as a tech writer

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.