[intrasight]

The documentation IS the product. As a top Navy brass once said "A nuclear destroyer is a floating SGML document".

The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders.

[tejohnso]

> The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders

Can you provide some examples? I've never seen a technical writer job post on this site as an individual post, and I don't see a single mention of documentation work in the recent Who's Hiring post.

[mikelevins]

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.

[trynewideas]

> Among professional tech writers and editors, "engineering documentation" is a pejorative phrase.

Not here. It's documentation written by and for a different audience, and it's valuable. As a professional technical writer and editor, I vastly prefer it over having engineers who won't write anything.

Tech writer value comes from adapting engineering docs for other audiences and use cases: identifying what context needs to be there (or doesn't), providing the value prop, demonstrating real-world workflows, presenting it in a broader narrative of productive usage, and finding ways to make it all confirmable and maintainable over time.

But we aren't (often) engineers, and we need those engineer-written docs as a starting point for our own understanding. I'd avoid ever being pejorative about that. The problem's usually with a culture — or leadership — that believes engineer-written docs are enough for non-engineering users, and that all any tech writer should do is proofread and publish them.

[mikelevins]

Your point is well taken. Consider my remark a bit of hyperbole--though I've definitely been in more than one conversation in which tech docs professionals described something as "engineering docs" with the clear meaning that it fell below some acceptable standard.

[gavinhoward]

You sound like you know your stuff.

I'm a one-man operation, and I want to have great docs, so much so that I even spend lots of time on docs in my free time project. [1]

Besides "know your audience," "understand your purpose," "proofread," and "test your docs," what advice can you give a programmer to be a great technical writer?

[1]: https://git.yzena.com/gavin/bc/src/branch/master/manuals

[mikelevins]

Being a great tech writer is pretty ambitious. Maybe start with wanting to be a competent one.

The way I learned was by being a junior writer at Apple surrounded by much better writers and professional editors. They assigned me what they thought I could do. They reviewed my work and taught me to make it better. The editors were generous enough to not only correct my mistakes but teach me why they were mistakes.

Not everyone has that opportunity, obviously.

Write a lot. Seek good feedback.

Good feedback tells you whether the reader learned what you meant to teach. It tells you how hard it was for the reader to learn it, and where the text was confusing or hard to follow or just plain hard to read.

The best-quality reviews I've ever gotten were from professional technical editors--no surprise, since that's their whole job! Still, you can do pretty well if you can find a smart, literate person who is comfortable telling you clearly what works and what doesn't in your work. What you need to know is whether your work engages the reader, is easy to read, is clear, and conveys the knowledge you intend.

You'll have to write and write and write. Write a draft and get it reviewed. Fix its weaknesses and get it reviewed again. Repeat until you just can't make it any clearer, simpler, and more successful.

Write about different subjects, then take those drafts through the review process.

Review your own writing, but not too many times, and leave enough time between readings. If you try to review too soon after you've written a draft, or too many times, then you'll miss a lot of mistakes because you'll see what you expect to see instead of what's actually on the page. The right limits might be different for different people; for me it's best to wait at least a day after I've written something or previously reviewed it.

Oh, and I should add: print your drafts and mark them up with a red pen. It's a different experience from editing and correcting text on a screen, and I find it helpful in ways that differ from online editing. If you want to try it then you might like to consult this cheat sheet:

https://amstp.northwestern.edu/documents/proofreading-marks-...

Read about writing. The Elements of Style is dated, but still good. The same goes for Words Into Type. The Chicago Manual of Style is a huge tome, but is a standard for good reason. Every Page is Page One is helpful, especially for writing documentation that winds up on the web.

Publications departments generally supplement references like these with in-house style guides. You might see if you can get your hands on one or two of these. Their main purpose is generally to teach new writers how to sound like the particular pubs department, but they also encode stylistic decisions that are intended to keep the text clear and accessible. You might not want to slavishly imitate any specific house style, but reading a few guides and thinking about what they're trying to accomplish can help you think critically about your work and develop your own style.

Apple's current style guide is here:

https://support.apple.com/guide/applestyleguide/about-the-gu...

Wiley and Sons has one here:

https://authorservices.wiley.com/asset/photos/House_style_gu...

Cisco's style guide is here:

https://img1.wsimg.com/blobby/go/31485ed6-9671-47cc-b0c0-353...

If you can think of technical publications that you admire, see if you can find the style guide that governs them. Read it and think about why they're giving the advice they do. Cherry pick the good thinking and apply it to your work.

Take a look at Diátaxis, which provides a nice structured way to think about the different kinds of tech writing and their different purposes.

https://diataxis.fr/

If you think of a question I didn't answer, ask. If I know the answer or have an idea how to find it, I'll let you know.

[gavinhoward]

> Being a great tech writer is pretty ambitious. Maybe start with wanting to be a competent one.

This made me sad, but the rest of your reply drove it home. Yes, I can only be competent. Oh well; it's still better than the average.

I'm bookmarking your reply; there's so much there. A lot of it I have done, and a lot I haven't.

And you answered everything I could think of. Thank you.

[trynewideas]

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

[giraffe_lady]

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.

[habosa]

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

[simonw]

"A nuclear destroyer is a floating SGML document"

I love that quote so much. Any more details on where it comes from?

[intrasight]

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.

[j45]

Well said.

In addition to writers on the team it’s important to ensure all developers are writing and developing their writing skills as much as coding skills.