DeborahWrites

Yes. Yes it is.

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.

An insight into the number of decisions a tech writer makes, even in a short document.

The point about advocating for your craft is a good one (and one of my weaknesses in my most recent perm role)

Some knowledge base or wiki tools build this in, but I don't know of a friendlier alternative for text-based formats (markdown etc.) Would love to hear of it if you find one . . . I suspect it would need to be git or something similar under the hood though?

Yeah, if your primary contributors aren't already comfortable with version control, you likely want to choose another toolset.

Capitalization would probably be a good idea, based on the comments here! Thanks!

Very valid question. I have tested it a little! I wrote it because a less technical tech writer was asking me a ton of questions, and he found it helpful. I also got a non-technical marketing person to review it, and she said she was able to learn a lot from it (those are the two people I thank in the intro)

It's obviously not going to get someone up and running: it's not a hands-on practical guide. But there are already quite a lot of those out there (for instance, most static site generators have acceptable getting started docs) The aim is to provide the missing conceptual info that's usually assumed by the creators of tools, but that not all tech writers have. Ideally, it should make them feel more comfortable following, say, an intro to git tutorial, because they have a bit more context/explanation backing them up.

Thanks for pointing this out. The post starts from the assumption that people have at least heard of "docs like code", because it's a widely-used term/practice in tech writing. So I was aiming at tech writers who heard the term, but lacked the knowledge to use the technique (original draft of the post was in response to a less technical tech writer asking me a ton of questions)

But perhaps I need to explain this up top, rather than hoping people will hang in there until the explanatory section.

Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.

This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.

Is there some rule that design tool companies have to be arseholes?