I've never understood writing as a specialization without any subject matter knowledge. For example Journalism degrees are often the first step in becoming a writer for a newspaper. The journalist ends up in the 'business' or 'politics' team even with no experience in these fields.

My naive suggestion for improvement would be to develop technical writing skills in addition to another degree or field. Want to write about science? Then do a science degree as well as a writing course.

Same with documenting software. Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics.

I think the article supports my view. The author hit a limit at his workplace because he specialised in writing without a deeper knowledge of what he was writing about. Instead of gaining that knowlege prior to working he had to learn on the job, which is fine but not ideal if it's not necessary.

At our organization we have a nontechnical sprint tester that executes manual tests and creates customer facing documentation. This sprint tester is part of our pull request approvals on our new feature branch builds.

The engineers write the unit tests, integration tests and create the initial draft of a manually executed (zephyr) test.

The sprint tester enhances the manual test and also creates the customer facing documentation/training content. What’s been nice about this is if the sprint tester finds its overly complicated to explain a new feature they can provide feedback about the design before it gets merged into the production builds. In this way they’re not just documenting what’s been done, but are contributing to the design.

Teams that really deliver well pull folks that work in supporting roles into the engineering & product team culture. Transactional relationships hit limits depressingly quickly - they also become toxic in ways that hurt the product you're trying to build.

If you treat your supports as equal team members you can attract and retain amazing talent that helps you iterate and deliver good products quickly. If you throw tasks over the wall and let people indulge in power fantasies you're wasting your time.

As much as I appreciate a well turned phrase, I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the topic.

I find tech writing skill to be necessary but not sufficient to competent at technical writing. GPT-3 is more than sufficient if my goal is phrases that sound reasonable may or may not capture the essential concepts

____Response to Article____

Engineers are rarely good at writing technical documentation, especially compared to technical writers (that is “secretaries” per author’s lingo) which by definition, should be. Engineers generally cost more than technical writers. Good technical writing saves engineering time both during AND after the documentation is produced.

Author spends large amount of time, to poorly express that to be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context.

____System for to Producing Tech Docs____

Anyone looking for a good system of producing documentation should check out:

https://documentation.divio.com/

Which has a 30-min presentation:

https://m.youtube.com/watch?v=t4vKPhjcMZg

Prior HN posts on the system are here:

https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....

I was joking with my boss the other day that the way I start out my technical writing (which I hate because it is such a different skill set) is to start “talking shit” and then I self-edit based on the fear that someone is going to call me out for this or that, and then I have my boss look at it and edit it before it goes anywhere.

It’s my new framing of it because I think that storytelling is fundamental to producing useful information. Also, I was a drama major w/ comp sci minor, so I’m probably doing what I was meant to.

Technical writing should evoke emotions, not at 6 or above in a 1-10 scale of intensity, but shit, say something or what’s the point? There’s always drama at work with enough people, always politics. Sprinkling a bit of that is actually healthy imho. Not that you want cringe, but the tone, it’s colored different, when you are describing why port numbers were chosen, for example. Tell people stories.

Also, be willing to invite someone else to shape and change even the things you feel the most conviction about. Too often we put ourselves into a cultural prison where we insist on making measurable contributions like an API or some cool feature that we can “specialize” in. Specialize on your own time, that’s my advice. At work, do something special, don’t specialize. It’s a myth.