Did Sisyphus feel condemned? Or was he grateful to practice being the best damned rock pusher in the universe?
Just a thought that popped into my head while editing more legacy doc. Totally unrelated.
“There are only two kinds of documentation: the one that people always bitch about and the one that nobody uses.” Thanks++, Bjarne Stroustrup.
me: Me? I'm a tech writer.
civilian: So is a tech writer just a frustrated novelist?
me: No, but I've been asked many times to write fiction, and that's frustrating.
The beauty and the horror of technical writing is when your audience isn't surprised.
The tech writer’s tree falling in a forest is the feedback form at the bottom of a help topic, only the sound is "tHiS sUcKs!1!!"
I feel that the first rule of tech writing is empathy.
Photo of various hoses snaking around in a boat locker
Why should devs get all the fun with composability?
Imagine trying out simple things then connecting them into more sophisticated things.
Lather, rinse, repeat until you have your own custom solution.
And there’s that sweet hit of dopamine each time you do it.
egopontem.com/blog/cli-sor...
Photo of the front cover of a book titled Food & Drink Infographics.
Photo of a book with a foldout on processed food.
Photo of a page in a book with a reproduction of a poster on olive oil, in French.
Photo of a page in a book with an infographic on edible insects.
In the damp basement classrooms where they trained tech writers, they forbade us not to entertain our audience.
I’m here to say that we can inform *and* entertain. Behold the proof that is this coffee table book! And it has my fave foods: processed food, olive oil, and bugs you can eat.
me: “If we clean up our broken doc workflow then the intern can migrate content and train us on an open source toolchain in about 3 months.”
other writers: “This 4-digit/seat proprietary knowledge base precisely duplicates our broken workflow. It should take about 3 months for the next 2 years.”
There are 2 kinds of left-handed people with fountain pens: elitist wankers and super heroes.
MS Word is like trying to type with boxing gloves, only not as productive.
spouse: Why is it taking so long to write your mother an email for her apple crisp recipe?
me: They whined about Michelangelo taking too long too.
#revisereviserevise
Photo of hoses in a cramped space.
Migrating to docs-as-code is a big step for a doc team. Congratulations!
There’s a big next step: Now you can easily process your doc set on the command line. Connect things together, see what works, see what doesn’t. Write more, let the machine do the fussing.
egopontem.com/blog/cli-sor...
Hoping that power returns sooner than later in Spain & Portugal.
Photo of a cat sleeping on a chair in a thrift shop
I posted a fresh article but I feel bad about it. Let me apologize now for the horrible regret you’ll feel after the elation of “getting” redirection on the command line. You’ll wish you could have taken advantage of it sooner in your life.
egopontem.com/blog/cli-cat...
Photo of Farley Mowat’s gravestone in Port Hope, Ontario
“As far as I’m concerned People of the Deer did nothing but good for individual people, the survivors... Nobody was going to pay any attention to them unless their situation was dramatized, and I dramatized it.”—Farley Mowat on being criticized for bending the facts.
If by “productivity” you mean word processor, spreadsheet, slide presentation, etc: Google Suite (or whatever it's called this week). Does what I need, doesn’t get in my way otherwise. Clients like it for review comments and rev history.
In a world where coders who write seem to muster more respect than writers who code, the response from tech writers to the challenges posed by the intersection of automation, multichannel delivery, and docs-as-code is weak, if not absent.
passo.uno/tech-writing...
Great article, thanks for sharing.
Kinda related: I just talked with a consultant about training “coders who write” to communicate better. I yammered on about passive voice and markdown. He wasn't interested, he wants to train his team on soft skills when dealing with clients.
Make sure your CSV files have the same columns:
```
head -qn1 *.csv | uniq
```
Merge them (with a single column header):
```
head -qn1 *.csv | uniq && tail -qn+2 *.csv
```
And sort them:
```
head -qn1 *.csv | uniq && tail -qn+2 *.csv | sort
```
I could go on.
Just switched from ChatGPT to Google Gemini, included with my Google Workspace subscription. It works well enough for my needs. I find myself iterating more for coding than I did with ChatGPT.
Technical Writing by Richard W. Smith
Copyright 1963 by Barnes & Noble, Inc.
Chapter 12 The Mechanics of the Trade
Chapter 13 The Future of Technical Writing
Plus ça change. I found this in a used book shop when I had just started my career. Over 60 years later our tools have changed but the challenges haven’t.
Nice. They're handy, inexpensive machines, right?
In my homelab I have 2 Lenovo M series ThinkCentres, also with 16 GB and SSD. They run headless with Debian, Docker, Coder, git, Syncthing, and Samba.
Indeed. “Nothing is emphasized when everything is emphasized.”
Screenshot of Emacs editor
Am I showing my age? I prefer Emacs the same way I prefer stick shift or a 35mm camera. They do only what I tell them to and don’t fall over themselves (and me) to do anything more. Sure, Emacs is always ready to do more, but only when I decide.
My experience with each:
- Confluence: Better for multiple page doc sets
- Notion: Better for single-page doc, like blog draft, checklists, tables of stuff
Both have decent commenting. Confluence is integrated nicely with the rest of the Atlassian universe. I prefer Confluence's editor.
Indeed. In my case, public libraries were my remote office during much of the pandemic.
Tech writers do it step by step.
Nothing is emphasized when everything is emphasized.
Photo of a walkway along a cliff wall in Caminito del Rey, Ardales Spain.
A picture is worth 3 orders of magnitude in words, a video 3 orders in pictures. The time it takes to make them is only 1 order of magnitude. Or, how to argue with your manager.
