TypeSpec reminds us why OpenAPI exists in the first place

I’ve recently found out about TypeSpec, a new language aimed at describing web APIs, through an interview that bears the provocative title of API Design in the Post-OpenAPI Era. Leaving aside the fact that OpenAPI is very much alive, what left me stupefied was the assertion that OpenAPI files should be “automatically generated artifacts and nothing more”. After digging a bit, I found the picture to be slightly more reassuring, but still quite representative of a world that keeps steering away from human-driven design to bury itself in curly brackets paradises.

Failing (and surviving failure) as a technical writer

What does it mean to fail as a technical writer? How does one get up again? How can we correct course and rekindle the fire that helped us power through rejections, layoffs, and ostracism? Is there any switch we can toggle so that folks understand what it is that we do and provide us with the resources we need in order to contribute a verse? I’ve been thinking about all this since I became a tech writer; now I want to share some of those thoughts with you.

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.