We want to hear from you! Get published, get paid, and help developers worldwide grow.

https://www.phparch.com/editorial/write-for-us/

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

> A release announcement should never include the phrase, “various improvements and bugfixes.” You might as well boast that the team proudly breathed air throughout development and used the latest version of the Internet.
- https://refactoringenglish.com/chapters/release-announcements/

The #techcomms and #accessibility communities lost a strong, kind, intelligent, wonderful, beautiful, and generous person to cancer on Monday 9 June, her birthday. Rest in peace, Char James-Tanny. You will be missed so much by so many.
#techcomm #TechWriting #CharJamesTanny

Recurring #TechWriting issue that I still haven't found a good solution for:

Is anyone aware of a decently reliable automation for reformatting #Markdown text that previously used line length limits of 80 characters and forced line wraps, to one sentence per line?

Must preserve all Markdown formatting including tables and fenced code blocks.

(If you think this is trivial and can be solved with a sprinkling of regex — nope.)

Boosts appreciated!

This is what I think about AI's impact on writing as well. My belief is that we have to weather the storm of overly eager decisions by non-experts to replace people with AI ... and to quote a friend, "pick up the pieces later".

With writing, sure, it's really easy to vomit out a brochure copy, but you still need a writer to give it a human voice and to check for hallucinations. For high-level, complex tech writing that I do good luck trying to generate that.

Clients will sniff fakery a mile away and avoid your company like the plague.

We need to apply AI to our workflows in a more realistic way, not in a sci-fi way.

https://youtu.be/fJGNqnq-aCA?si=cE0uPBw-_mT4XYvt

I wrote up a tech-writing technique I call the assertions document. It helps you rapidly develop your own understanding of a new-to-you topic by getting your subject-matter experts engaged in the docs project as quickly as possible, and even eager to help you—largely by giving them ways to tell you how you're wrong. #TechWriting #TechnicalWriting https://fogknife.com/2025-04-04-assert-your-way-to-stronger-technical-writing.html

Here's one for the tech writers, writing about tech writing: #TechWriting #TechnicalWriting

If you're programming/coding I'd love your help here:

What are some of the best examples you've seen (that are public/I can view - any language is fine) of programming tutorials and/or example code?

I'm looking for the best examples that illustrate how a a program is put together, the patterns it's using, so that you do the same yourself.

What a wonderful day an #UniventionSummit . I enjoyed meeting long term colleagues from other companies, getting to know inspiring new people, and exchanging experiences about #techwriting . I'm looking forward to the recordings of the talks, especially of "Digitale Enteignung - Wie Big Tech Wirtschaft und Demokratie zerstört" from Martin Andree.

As part of my quest to make #GNOME i18n rock, I did some #TechWriting and improved the Damned Lies OpenAPI documentation.

Can you find the 7 differences?

Dear Geeks:
A friendly #TechWriting reminder. Just because YOU have a big vocabulary doesn't mean all your readers do.

Some people are young, or haven't had the opportunities to encounter as many words.

Some people don't have YOUR language as their native language.

All user facing strings _must_ be written with that in mind.

Here's an example of how NOT to do it. How many young coders or people new to English do you think know the meaning of "obsolescent" ?

How many native adults?

Tech writing managers: How do you hold people accountable for writing quality?

I’m managing a team of writers again, and I find this is the missing piece. People fixate on what they get measured on, and writing quality is difficult to quantify. User satisfaction ratings can be a proxy of quality, but the docs I oversee have a low volume of feedback, so it’s not a strong enough signal.

Trying out @omnivore and am pretty happy with it! It doesn't play as friendly with Firefox, but fixed it thanks to their docs (yay #techwriting) and was sad text to speech not available for Androids yet. I do depend on it a bit. (I like to listen to articles while working out.)
But the thing that I am super excited about, besides it being open source is that it can funnel your articles to #Obsidian.

I have to admit my current system isn't working for me.

I have a webhook documentation thing to write, my brain is STILL not booted up and it's already 12pm. HELP

You must be in the right job when you get a flood of tickets on a day where you feel really tired, but you're immensely happy and grateful that you have these tickets anyway.*

* I struggled hard to transition from journalism/marketing to #techwriting and I'm always immensely grateful I managed to make the transition and have notched almost 2 years of experience to date Excited to learn things that were only concepts to me before.

Today, my main task at work is to set up an ITSM portal and also pretend to be a few pissed off customers.
I like.

OK, so first life update is that I'm looking for work.

Fully remote, perm or contract, senior docs or docs lead type stuff.

Assorted relevant hashtags #writeTheDocs , #techWriting, #docsAsCode, #FediHire, #API

Join me at Philly .NET - Learn, Share, and Grow: How to Become a Microsoft Learn Contributor https://meetup.com/philly-net/events/298279616/.