This past weekend I’ve been experimenting with AI-assisted coding to port basic docs-as-code elements to old operating systems and platforms, such as the venerable Intel 386. While this might strike you as a bizarre display of futility, I find this sort of retrocomputing exercise to be quite beneficial, if not enlightening. Something just clicks when you stop and walk backwards.| passo.uno
I’m a terrible user of documentation. I tend to consume docs in a hurry, reading diagonally, Control+Fing my way to things. I generally mistreat the interface of docs until I obtain something resembling an answer. I do this because I’ve little time and I need to fix issues fast. I love examples I can copy and paste. I’ve little patience for verbose documentation and even less for docs that look like they were written without care or skill. I’m not only bothered by inaccuracy, but also...| passo.uno
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 steerin...| passo.uno
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 worlds in our heads while we waited for a few kilobytes to load in memory. Those manuals still hold valuable lessons for the software documentation we write today.| passo.uno
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 experience to driving all the way from Chicago to San Francisco on a BMW Isetta: feasible, though not very comfortable nor fast, and certainly not fun for your derrière.| passo.uno
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 push formal tech comms education forward (at least in Europe). While the role has grown in popularity, technical writers are still a small fraction of the total workforce in the tech industry. The question is so powerful, though, that I canno...| passo.uno
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 technical writing. Perhaps you’ll find some words of inspiration here. Or maybe not.| passo.uno