Posts on passo.uno

Recommending books for technical writers that aren’t old technical manuals is hard.

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).

A month ago, Lana Novikova asked me to imagine the future of software documentation.

Some technical writers in my network are genuinely worried about their professional future in the AI age.

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 technical writers we want to know if the docs we’re writing are accomplishing their goals.

I’m not only a technical writer and an avid collector of old manuals: I’m also a gamer.

Every once in a while, startup founders and managers decide that they need someone to create and manage their docs –perhaps after reading this letter.

I’ve already presented the gear I use at work.

Of documentation many are the kinds throughout the web—unnumbered, since no writer can count their multitudes, nor rightly learn the ways of their wild nature; wide they roam, these patterns, as far as Internet sets.

I’ve been working as a writer in tech for more than 15 years now.

A few days ago I published a repository for the English Programming Language, a tongue-in-cheek parody of README files.

Dear software developer, You might have heard about technical writers, those mythical creatures.

A friend asked me the other day how I became a technical writer.

Should docs stay with the code they document?

Laura Vass from API the Docs asked me the other day why technical writing has such a bad rap.

Had some fun designing this technical writing map using Inkarnate.

Technical writing requires appropriate gear to be done in a way that’s both healthy and productive.

Just when we thought that we wouldn’t be replaced by WriterBot, a mounting concern is ruining many a breakfast: Bad actors could still get hired as technical writers by feeding take-home assignments to ChatGPT and presenting the resulting soliloquy as the…

There’s been a lot of fuss about ChatGPT, OpenAI’s conversational bot, and its docs capabilities.

Every now and then, people ask me how one can become a technical writer for software companies.

A recurring question from people entering the tech writing profession is “Should I learn to code?”.

Almost a year ago I had this crazy idea of writing a children’s book on OpenTelemetry.

While thinking about unconventional technical communication, like comic books, children stories, and games, a thought occurred to me that they’re all attempts at hitting the core of what a product is and does, that is, its truth.

As a psychologist, I’m quite familiar with Maslow’s hierarchy of needs.

I had lots of fun creating this D&D style skills tree for technical writers.

There’s a string of questions that haunt every technical writer and documentation manager at some point in their careers: How do we know that we’ve done a good job?

I wanted to write this post for a long time, but got to it only now, perhaps because it’s a natural segue into Let’s blog more about technical writing.

I’ve been wondering for a while why I don’t see more blogs on technical writing, tech comms, and technical documentation.

Prose linters are great at checking documentation against style guides, either in code editors or when running a CI/CD pipeline.

As a technical writer, I often want to know what works and what doesn’t in the docs I’ve released.

Beholding Stripe’s excellent documentation and wondering how they’ve built it is a modern technical writing trope.

A few months ago, I drafted a technical writing syllabus.

It’s my ritual: every time I enter a secondhand bookshop, I go straight to the Sciences section and search for old computer manuals.

Almost two years passed since I published my tips for working remotely.

Despite the massive growth of docs-as-code as a documentation ethos, I continue to be surprised, year after year, by the lack of robust docs-as-code tools.

A colleague asked me the other day what’s my favourite way of extracting information from subject-matter experts (SMEs).

I get it.

Code linters support developers by catching errors and stylistic issues in code, such as bad formatting or keywords in the wrong places.

There was this discussion at work regarding docs in products, so I sketched a diagram to illustrate the main types of embedded docs, and their place in the product writing continuum, from UX writing to technical writing.

I’ve been working with remote teams for years.

From time to time, people ask me about technical writing and the type of work I do.