RSS Parrot

What docs as code really means

https://passo.uno/what-docs-as-code-means/

Published: October 20, 2024 09:00

I’ve recently started a new job as a documentation engineer. My work is largely the same as that of a technical writer, but the sound and semantics of my new title gave me some pause and made me think about what it really means to be doing docs-as-code. To…

Webinar: Contributing to Open Source Documentation Projects

https://passo.uno/webinar-open-source-docs-contributions/

Published: September 26, 2024 16:00

Some months ago I wrote a post about open source docs contributions. My dear colleague Scott Abel (The Content Wrangler) found that to be a good topic for a webinar, so today I hosted Contributing to Open Source Documentation Projects, where I expanded my…

TypeSpec reminds us why OpenAPI exists in the first place

https://passo.uno/typespec-openapi-api-design/

Published: September 2, 2024 13:30

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…

Failing (and surviving failure) as a technical writer

https://passo.uno/technical-writing-failures/

Published: August 18, 2024 19:00

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…

Discussing Markdown and structured content with Niklas Begley

https://passo.uno/markdown-structured-content/

Published: July 23, 2024 13:00

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…

How to set up your tech writer up for success

https://passo.uno/how-to-tech-writer-success/

Published: July 6, 2024 14:00

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…

Contributing to open source docs as a technical writer

https://passo.uno/contribute-open-source-docs/

Published: June 24, 2024 16:00

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…

Review of Technical Writing for Software Developers

https://passo.uno/review-technical-writing-software-developers/

Published: June 9, 2024 14:00

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…

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

https://passo.uno/posts/technical-writing-is-not-a-dead-end-job/

Published: May 29, 2024 20:00

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…

Things I remind myself when working with others

https://passo.uno/tips-working-tech-writers-team/

Published: May 12, 2024 11:00

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…

My favorite books for tech writers

https://passo.uno/best-tech-writing-books/

Published: April 25, 2024 11:00

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…

The pros and cons of using Markdown

https://passo.uno/pros-cons-markdown/

Published: March 27, 2024 11:00

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…

Technical writing in 2049

https://passo.uno/tech-writing-predictions-2049/

Published: March 17, 2024 16:00

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…

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

https://passo.uno/ai-anxiety-tech-writer-howto/

Published: February 10, 2024 14:00

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…

Signs that you need a technical writer

https://passo.uno/signs-need-tech-writer/

Published: January 17, 2024 16:00

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…

Docs observability, or measuring docs inside a product-docs system

https://passo.uno/docs-observability-do11y/

Published: January 8, 2024 08:00

As technical writers we want to know if the docs we’re writing are accomplishing their goals. In other words, we want to know how good are docs relative to the business goals they’re aiming to support or improve. Are docs serving their purpose? Which of…

What tech writers can learn from video game manuals

https://passo.uno/video-game-manuals-docs/

Published: December 13, 2023 21:00

I’m not only a technical writer and an avid collector of old manuals: I’m also a gamer. One of the bits I always enjoyed about video games were the manuals, from the slim booklets that accompanied arcade games to the hefty guides that helped build virtual…

Tips for hiring your first technical writer

https://passo.uno/tips-hiring-tech-writers/

Published: November 8, 2023 10:00

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. Some contact me to understand how they should go about hiring for a tech writer. Since I’ve already…

Chat with Tom Johnson about AI and tech comms

https://passo.uno/ai-tech-comms-podcast/

Published: October 23, 2023 06:00

I had a cool chat with Tom Johnson (idratherbewriting.com) about AI and its impact on technical writing and documentation. Along the way, we also had the chance of discussing open source docs and the challenge of being a first-time contributor.

My favorite tech writing tools

https://passo.uno/favorite-tech-writing-tools/

Published: October 22, 2023 07:00

I’ve already presented the gear I use at work. Here’s my list of favorite software tools for technical writing, the ones I couldn’t do without in my day-to-day routine. They mostly apply to a docs-as-code, software documentation setting. Notice that I’m…

Bestiary: On Doc Types and Other Animals

https://passo.uno/docs-bestiary-taxonomy/

Published: September 23, 2023 16:00

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. Let me, o reader, speak of these…

Once Upon a Time There Were... Docs

https://passo.uno/write-the-docs-opentelemetry-children-story/

Published: September 20, 2023 05:00

Here are the video and abstract from my talk Once Upon a Time There Were… Docs from Write the Docs Atlantic 2023.

Tips for job hunting as a technical writer

https://passo.uno/job-hunting-tech-writers/

Published: September 16, 2023 09:00

I’ve been working as a writer in tech for more than 15 years now. During this time I’ve been at five different companies. I’ve done tons of interviews and got more than a dozen offers, some of which I ended up accepting. It didn’t always start with…

An experiment in humorous documentation

https://passo.uno/experiment-humour-documentation/

Published: July 17, 2023 07:00

A few days ago I published a repository for the English Programming Language, a tongue-in-cheek parody of README files. I had a hunch and posted it on Hacker News at 3 AM. When I woke up, the repo was on the front page and already racked up 200 stars on…

A tech writer's letter to software developers

https://passo.uno/tech-writers-letter-to-developers/

Published: June 25, 2023 14:00

Dear software developer, You might have heard about technical writers, those mythical creatures. You might even be working with one. Whatever the case, I’d like to send you advice on how to achieve a healthy work relationship with technical writers so that…

How did I become a technical writer

https://passo.uno/how-did-i-become-tech-writer/

Published: June 18, 2023 09:00

A friend asked me the other day how I became a technical writer. The question gave me pause and made me realize that, while I wrote about how to become a technical writer, I hadn’t yet written how I had become one. For all who may be interested, here’s how…

Docs-as-code topologies

https://passo.uno/docs-as-code-topologies/

Published: May 14, 2023 20:00

Should docs stay with the code they document? Or should they rather be in a separate repo, fully managed by tech writers and docs site developers? The matter of where docs should be living when doing docs-as-code isn’t easy to untangle. With the following…

Episode 33 of API the Docs podcast

https://passo.uno/ep33-api-the-docs-podcast/

Published: April 13, 2023 14:04

I’ve enjoyed doing this one a lot! Thanks Laura Vass and API the Docs! :-) https://apithedocs.org/podcast/love-letter-technical-writing-interview-fabrizio-ferri-benedetti-passo-uno

We need more technical writing in popular culture

https://passo.uno/tech-writers-pop-culture/

Published: March 30, 2023 14:00

Laura Vass from API the Docs asked me the other day why technical writing has such a bad rap. My answer was that technical writing’s real problem is not having a rap at all: not only is our profession relatively unknown, it almost never appears in popular…

High fantasy map of technical writing

https://passo.uno/tech-writing-fantasy-map/

Published: March 12, 2023 12:00

Had some fun designing this technical writing map using Inkarnate. Because tech writing feels like a high fantasy quest at times.

My technical writing gear (how I work)

https://passo.uno/technical-writing-equipment/

Published: January 29, 2023 17:00

Technical writing requires appropriate gear to be done in a way that’s both healthy and productive. While it’s true that communicating with subject-matter experts and writing documentation can be done on a tiny Chromebook, I would compare such an…

Hiring technical writers in a ChatGPT world

https://passo.uno/hiring-tech-writers-chatgpt/

Published: January 4, 2023 10:00

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 rise of WriterBot

https://passo.uno/openai-tech-writing-howto/

Published: December 3, 2022 15:00

There’s been a lot of fuss about ChatGPT, OpenAI’s conversational bot, and its docs capabilities. Some dismissed its skills; others are thinking of selling their possessions and flee to Patagonia. Let’s do something different and entertain a hypothetical…

How to become a technical writer

https://passo.uno/how-to-become-a-technical-writer/

Published: November 7, 2022 13:00

Every now and then, people ask me how one can become a technical writer for software companies. Answering that question has always been difficult, as there is no clear career path for becoming a tech writer, nor a demand for tech writers such that it’d…

Learning to code as a technical writer

https://passo.uno/tech-writer-learn-to-code/

Published: October 30, 2022 10:00

A recurring question from people entering the tech writing profession is “Should I learn to code?”. This query has become hugely popular in the docs-as-code age, where writers and developers live in the same DevOps trenches, eating the same CI/CD rations…

My first children’s book is about... OpenTelemetry

https://passo.uno/opentelemetry-children-book/

Published: October 14, 2022 13:30

Almost a year ago I had this crazy idea of writing a children’s book on OpenTelemetry. In this, I was inspired not only by my lifelong love for illustrated stories, but also by the example set by Gently Down the Stream, a children’s story on Apache Kafka.…

Circles of Product Truth

https://passo.uno/circles-product-truth/

Published: September 19, 2022 14:00

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. I developed this picture…

Docs Hierarchy of Priorities: A Proposal

https://passo.uno/docs-hierarchy-of-needs/

Published: August 28, 2022 11:00

As a psychologist, I’m quite familiar with Maslow’s hierarchy of needs. It’s an extremely popular framework for human motivation. The hierarchy, often pictured as a pyramid, states that people look for certain things following a certain order: First…

Tech Writing Skills Tree

https://passo.uno/tech-writing-skills-talent-tree/

Published: August 11, 2022 22:00

I had lots of fun creating this D&D style skills tree for technical writers. I made this one out of the belief that there are multiple ways of becoming a tech writer, and that tech writers can specialize.

Measure it till you make it

https://passo.uno/tech-writing-metricks-kpis/

Published: August 6, 2022 14:00

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? Have we been successful given our limited resources? How can we get better at what we do?…

A love letter to technical writing

https://passo.uno/why-technical-writing/

Published: July 18, 2022 22:00

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. Whatever the reason, I’m in a moment of my life where I feel compelled to say out loud why I love…

Let's blog more about technical writing

https://passo.uno/we-need-more-writing-on-tech-writing/

Published: July 15, 2022 22:00

I’ve been wondering for a while why I don’t see more blogs on technical writing, tech comms, and technical documentation. I’ve been in listening mode for years, and beyond Tom Johnson’s excellent blog, it’s hard to find more content around technical…

How to introduce prose linters at your workplace

https://passo.uno/prose-linters-implement-workplace-howto/

Published: July 3, 2022 22:00

Prose linters are great at checking documentation against style guides, either in code editors or when running a CI/CD pipeline. They can capture issues in your docs that might have been overlooked by reviewers, thus avoiding costly mistakes. The bigger…

Do it yourself: User research for technical documentation

https://passo.uno/tech-writing-user-research-howto/

Published: June 24, 2022 22:00

As a technical writer, I often want to know what works and what doesn’t in the docs I’ve released. Oftentimes, I also want to know if the documentation is achieving its purpose. There’s a very good way of getting answers about the quality of your…

Markdoc is not what you expected, and that's a good thing

https://passo.uno/markdoc-review/

Published: May 11, 2022 22:00

Beholding Stripe’s excellent documentation and wondering how they’ve built it is a modern technical writing trope. It’s no wonder, then, that when Stripe announced that they open sourced their documentation format and framework, Markdoc, folks would get…

Technical writing syllabus

https://passo.uno/tech-writing-syllabus/

Published: May 2, 2022 22:00

A few months ago, I drafted a technical writing syllabus. It features all the topics that a senior technical writer should master at some point when working on software documentation.

Episode 3 of Let's Talk Docs

https://passo.uno/lets-talk-docs-podcast/

Published: March 2, 2022 23:00

Episode 3 of the Let’s Talk Docs podcast is out, hosted by Portia Burton and Eric Holscher (founder of Read the Docs and Write the Docs). Enjoy!

Why I collect and read old computer manuals

https://passo.uno/why-collect-read-old-computer-manuals/

Published: January 22, 2022 23:00

It’s my ritual: every time I enter a secondhand bookshop, I go straight to the Sciences section and search for old computer manuals. They’re very hard to come by, as their owners tend to throw them away once they stop using a particular device or piece of…

An update to my tips for working remotely

https://passo.uno/more-tips-for-working-remotely/

Published: December 20, 2021 23:00

Almost two years passed since I published my tips for working remotely. Now that remote work has become almost standard in the software industry, I felt like revisiting that list to add a few items. Enjoy!

Better docs, less pain: the case for new docs-as-code standards

https://passo.uno/docs-as-code-tools-open-standards/

Published: November 1, 2021 23:00

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. Most days it feels as if docs-as-code was a giant standing on feet of clay, on the fragile…

The Columbo Technique for Technical Writers

https://passo.uno/the-columbo-technique-for-technical-writers/

Published: October 21, 2021 22:00

A colleague asked me the other day what’s my favourite way of extracting information from subject-matter experts (SMEs). This is a big topic in technical writing, as most of our time at work is spent chasing engineers and project managers to get bits of…

How to assist API design as a technical writer

https://passo.uno/posts/how-to-assist-api-design-as-a-technical-writer/

Published: October 12, 2021 22:00

The programmatic equivalent of UX Writing is API Design. The words that you use to describe your API enable conversations between software and people - it’s just a bit more structured and mechanical. That’s why technical writers are uniquely suited to…

OpenAI and docs: AI-aided technical writing is here to stay

https://passo.uno/posts/computer-aided-technical-writing-is-here-to-stay/

Published: August 27, 2021 22:00

I get it. It’s hard to read articles about OpenAI’s coding and writing skills without feeling a shiver of neo-luddite panic running down your spine. Especially when one reads passages like the following.

Open source tools for REST API documentation

https://passo.uno/posts/open-source-tools-for-rest-api-documentation/

Published: June 23, 2021 22:00

A hands-on review of the most recent open source API documentation toolchains, such as ReDoc, Widdershins, and Elements, the newest solutions from Stoplight, among others. Get the slides here.

On personality in technical writing

https://passo.uno/posts/on-personality-in-technical-writing/

Published: June 20, 2021 22:00

Had this lovely chat with Chris Ward and Tom Johnson on personality and authorship in technical documentation for the Write the Docs Podcast. Enjoy!

First steps with the Vale prose linter

https://passo.uno/posts/first-steps-with-the-vale-prose-linter/

Published: May 20, 2021 22:00

Code linters support developers by catching errors and stylistic issues in code, such as bad formatting or keywords in the wrong places. The term comes from lint traps in dryer machines, which capture the tiny bits of fiber that separate from cloth.

Levels of embedded documentation

https://passo.uno/posts/2021-04-05-levels-of-embedded-documentation-1/

Published: March 3, 2021 18:35

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.

Working with remote teams: My Tips

https://passo.uno/posts/2021-04-05-working-with-remote-teams-my-tips/

Published: February 4, 2020 17:36

I’ve been working with remote teams for years. It didn’t always work well; sometimes the reason was the content I sent, but most of the time it was the content I did not send, the missed opportunities. The tool never mattered. Now I want to share what I’ve…

What is technical writing?

https://passo.uno/posts/2021-04-05-what-is-technical-writing/

Published: October 9, 2019 16:31

From time to time, people ask me about technical writing and the type of work I do. As not much is known about technical writing outside of the English-speaking world, I came up with a short answer. I hope you’ll find it useful.