Marc Paquette
banner
egopontem.com
Marc Paquette
@egopontem.com
27 followers 40 following 48 posts
Technical writing and other things 🌐 egopontem.com <> github.com/marcpaq
Posts Media Videos Starter Packs
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.
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...
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
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.
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...
“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.
Reposted by Marc Paquette
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...
Technical writing has a depth issue
Demoralized by the advent of LLMs, I see tech writing communities break ranks and flee. In a world where coders who write seem to muster more respect than writers who code, the response from tech writ...
passo.uno
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.
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.”
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.