Remix.run Logo
murderfs 8 hours ago

I don't think I've ever seen documentation from tech writers that was worth reading: if a tech writer can read code and understand it, why are they making half or less of what they would as an engineer? The post complains about AI making things up in subtle ways, but I've seen exactly the same thing happen with tech writers hired to document code: they documented what they thought should happen instead of what actually happened.

DeborahWrites 8 hours ago | parent | next [-]

You sound unlucky in your tech writer encounters!

There are plenty of people who can read code who don't work as devs. You could ask the same about testers, ops, sysadmins, technical support, some of the more technical product managers etc. These roles all have value, and there are people who enjoy them.

Worth noting that the blog post isn't just about documenting code. There's a LOT more to tech writing than just that niche. I still remember the guy whose job was writing user manuals for large ship controls, as a particularly interesting example of where the profession can take you.

parados 5 hours ago | parent | prev | next [-]

> they documented what they thought should happen instead of what actually happened.

The other way around. For example the Python C documentation is full of errors and omissions where engineers described what they thought should happen. There is a documentation project that describes what actually happens (look in the index for "Documentation Lacunae"): https://pythonextensionpatterns.readthedocs.io/en/latest/ind...

saagarjha 8 hours ago | parent | prev | next [-]

Not everyone wants to write code.

murderfs 8 hours ago | parent [-]

Yeah, but almost everyone wants money. You can see this by looking at what projects have the best documentation: they're all things like the man-pages project where the contributors aren't doing it as a job when they could be working a more profitable profession instead.

saagarjha 8 hours ago | parent [-]

While I do appreciate man pages, I don't think they are something I would consider to be "the best documentation". Many of the authors of them are engineers, by the way.

imtringued 7 hours ago | parent | prev | next [-]

A tech writer isn't a class of person. "Tech writer" is a role or assignment. You can be an engineer working as a tech writer.

Also, the primary task of a tech writer isn't to document code. They're supposed to write tutorials, user guides, how to guides, explanations, manuals, books, etc.

8 hours ago | parent | prev [-]
[deleted]