Treating documentation like a product

The Google developer relations team has hundreds of tech writers, they have their own career ladder alongside developer relations engineers.

This site isn't representative of all software jobs, or all software companies by any means.

That said I've also very rarely seen a posting for this. I've worked at a few companies that had 1-3 people doing it full time. But in every case I can think of they were exceptionally competent individuals who had started off in either support or engineering and gradually took it on as an explicit role because they were willing to do it and once they were the value was obvious.

Apple and Cisco are two examples of companies with large, well-organized technical documentation teams. I've worked on both teams. There are certainly many other examples.

I've also worked for a few startups on setting up their technical documentation processes.

My career in software started January 1, 1988 at Apple. Roughly 1/3 of my career has been as a technical writer, and 2/3 as a programmer. The two disciplines require comparable levels of knowledge and technical skills, but programming generally gets much better funding and other support.

There are several reasons for that. The most obvious is that you can't ship a software product without some programming, but you can ship one without any technical writing. It's generally a bad idea, but it's possible.

Another reason is that technical documentation is in almost all cases a pure cost center. You don't make money from your technical docs. Worse, you can always make docs better with more effort, so there's no theoretical ceiling on its cost. How expensive are docs? Well, how much have you got?

Yet another reason that docs get short shrift is that smart people tend to assume that they can write. They are often mistaken. Among professional tech writers and editors, "engineering documentation" is a pejorative phrase. Nobody thinks that they can write good software with no experience and no training, but many otherwise intelligent people make exactly that assumption about tech docs.

Also, it must be said that technical documentation is probably the least cool job in software, even less cool than compatibility testing. Nobody ever called a tech writer a "rock star" (although I can think of a couple that probably qualify).

I haven't seen a lot of hiring posts for tech writers on HN, either, but that doesn't surprise me. HN is sort of startup-oriented, and it usually takes startups a while to realize that they need professional tech writers. It happens when someone realizes that they're spending too much supporting customers and partners because they're not spending enough on docs. That's when they go shopping around for someone to help them fix that problem.

I've been that guy before, and I also know a good recruiter who specializes in that, in case anyone needs a contact.

Hi! I've been a technical writer at several startups, all B2B SaaS, mostly mid-stage 200-400 employee companies. In two of them, I was the first writer hired.

I'm not surprised that HN Who's Hiring posts don't target us, because I don't feel like tech writers are really the audience here. Smaller startups might benefit from a dedicated tech writer, but the resources are harder to justify. Larger companies are either contracting maintenance of existing sets or already have established teams.

So it's often that sweet spot combo of a funding round, new product launches, and eng/R&D scale-up or M&A where a startup decides that they need one or more dedicated technical writers to clean up and reorganize existing content and make maintenance more scalable. It's a specific, fleeting moment of hiring the first 1-to-5 writers, after which new writer positions fill pretty quickly via referrals, intern-to-hire, direct recruitment, or internal transfers. (I've been hired though three of those.)

If you search LinkedIn you'll find a bunch of openings. Here's one at ServiceNow, first result in the list: https://www.linkedin.com/jobs/view/3422041216

Quote was shared to me by the president of a defense contractor where I worked as a contractor on a project to surface (excuse the pun) that SGML document.

When is an animated GIF showing a series of complex steps better than a video of the same? The video has the advantage of offering things like audio, higher quality playback, the ability to be downloaded locally and played in VLC (where you can do things like zoom in or slow it down), etc. Maybe not all of those things are needed in every case, but even then video will get the job done just as well as a GIF and provide consistency with any instance where you do end up needing video's features.

Documentation in some ways is more of an important output than code.

Documentation serves to to create beginners with the source code and project.

When working with devs it’s made clear that what they are delivering is documentation of which working code is one part.

The ability to write sentences in documentation is as important as writing code.

Writing as one works (not after) and then editing is one of the only ways I’ve found that there is a chance, waterfall, agile or cowboy.

I've held that view before, but in practice adding friction to review and deployment doesn't accomplish much other than frustrating engineers.

Aside from that, the code review process is also too late. A better spot would be during the design process, then updated alongside the implementation to match. By the time you get to code review, the docs for the relevant code should naturally already be written, without needing to set and enforce a docs requirement.