Let's Talk About Writing in Tech

My contribution to this debate is that it isn't a developer problem it's a "beginner's mind" problem, which I personally characterize as "empathy"

Can one recall what it was like 15 minutes ago when you didn't know the answer, and how would you have changed the situation to foster the pathway that would have squared up the product's model with your mental model. No matter the product: library, webpage, physical tool, bureaucratic process, etc. If a human(s) made it, then managing the assumptions is a grade-A problem that requires managing throughout its lifecycle

Developers love to complain about bad requirements, but documentation is where one gets to provide the requirements to the reader, thus, is an empathy management exercise

As someone who spent a long time in technical writing, and wrote a decent-selling book about getting started as a tech writer, here’s my thought: The problems with software documentation/tutorials/etc. rarely have anything to do with writing skill—because the biggest challenge is not writing, it’s how to analyze and understand the audience and design what ‘documentation’ they need to get the job done. Separate skill(s), unrelated to writing. “Writing”, in fact, is the easy part. Think of it this way: you can write the most beautiful, elegant, correct JavaScript that’s ever been written: and it can be utterly useless. Beautiful code is good, but that’s not the goal or the focus.

The posts has a promising start, then abruptly ends.

Yes, developers need to improve writing skills. A good book on the matter is Chris Ward's Technical Writing for Software Developers, which I reviewed here: https://passo.uno/review-technical-writing-software-develope...

They also need to hire technical writers. Did the author know they exist?

I once worked for an organization known for providing good documentation.

This is how it worked:

They had a documentation-writing branch. And you (developer) knew that if you don't write documentation, they will. And then if will cost you _more_ time and frustration to review and correct what they wrote than to write it yourself and give to them.

So you did write it (and they proofread it, corrected grammar etc.).

I have a hunch that technical documentation may be one form of writing that LLMs won't be able to really help with beyond the mundane grammatical/structural advantages that it affords to any other form of writing.

AI is utterly swaggerless and I have a notion that a lot of what people enjoy from technical writing is the vibe they get from the writing; as much as the instruction.

Undoubtedly a big opportunity area for LLMs. I’ve recently observed engineers deliver LLM-generated (or iterated) docs that blow away any technical writing they had done in the past.

Network Engineering design docs can be somewhat formulaic structurally, making the LLMs job simpler. I imagine in the near future we’ll just ask them to follow doc templates or reference other designs within a RAG system to ensure there aren’t gaps in the doc, etc.