DeborahWrites

Yeah. AI might replace tech writers (just like it might replace anyone), but it won't be a GOOD replacement. The companies with the best docs will absolutely still have tech writers, just with some AI assistance.

Tech writing seems especially vulnerable to people not really understanding the job (and then devaluing it, because "everybody can write" - which, no, if you'll excuse the slight self-promotion but it saves me repeating myself https://deborahwrites.com/blog/nobody-can-write/)

In my experience, tech writers often contribute to UX and testing (they're often the first user, and thus bug reporter). They're the ones who are going to notice when your API naming conventions are out of whack. They're also the ones writing the quickstart with sales & marketing impact. And then, yes, they're the ones bringing a deep understanding of structure and clarity.

I've tried AI for writing docs. It can be helpful at points, but my goodness I would not want to let anything an AI wrote out the door without heavy editing.

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?

An approach to using AI that ensures you benefit from it, without damaging your thinking skills.

You're telling me the seemingly arbitrary 6 weeks of Prolog on my comp sci course 11yrs ago is suddenly about to be relevant? I did not see this one coming . . .

Yeah I freelanced for 4yrs before returning to employee-land in 2022. I think I'm going to go back to it eventually, but nervous in the current market.

This has a lot of appeal. I am instinctively wary of managers who can't do the actual job, which this obviously avoids. It also removes the 'management track', and presumably means you can see more progression as an IC (with a little bit of management). And I tend to agree major issues need to bubble up to leadership anyway.

Tangent but I am increasingly convinced the happiest company size maxes out around ~50 (give or take).

I'm belatedly learning this lesson (you'd think I'd have caught on earlier in my career) I very much want to stick to small young startups in future, but there's less demand for tech writers there.

The process in my mid-20s of realising I was not going to have the career I'd expected since my mid-teens was pretty rough. I eventually dusted myself off and pivoted, but it might have been healthy to mourn (although I can't imagine myself summoning my friends to a gathering for that purpose - but good for her, sounds like she had a sense of humour about it)

Yeah if an applicant/incoming hire is reaching out then definitely respond! But I'd wait for the applicant to initiate it - if the company does, the applicant is under pressure.

Every ~3yrs an article like this floats across my screen.

Every time, I think it sounds SO fun.

And then do nothing.

Given this time I have the excellent excuse of a new job, I don't expect to break the trend this year.

But one day . . . one day . . .

"The second practice I've adopted has been to hop on a few quick calls and trade some emails back and forth with people who haven't yet joined. These can and should be super casual (remember: they're not employees yet!)."

oooff. No please don't let this become a norm. A few checkin emails? Sure. But given that offers can be pulled, each of those chats is going to feel like an interview to the candidate. Every call is likely to cause stress - and from the candidate's point of view, they can hardly refuse.

"The goal with these encounters is to keep people intelectually curious. Just share with them what's going well, and what challenges lie ahead. And maybe you can get them to brainstorm with you on some interesting issues."

No. They don't work for you yet, so stop trying to get them to do work for you. They probably have more than enough on their plate wrapping up work/doing handover at their old place. And they may want to actually take a break between jobs - not take a couple of unpaid weeks where you keep dragging them onto calls to do work.

If someone in effect started trying to onboard me and get me working on company problems before I'd actually started, THAT would be far more likely to make me run away than if I had total radio silence.

I'm enjoying the recent small trend of gentle pushback against overly rigid planning.