Interesting read, though the writing itself is ironically quite clunky for an article about writing. It's bad enough that I still suspect it might be written by an AI.
It's worth noting that technical writing is basically two professions wrapped up into one:
- On one hand, there are traditional technical writers; folks with next to no coding skills who frequently edit technical content written by others. These individuals typically use a CMS to produce content (since they have very few technical skills), use Google Docs or Word to edit and create content, and make money in the range indicated by the article.
- On the other hand, you'll find, er, "technical technical writers." These are typically former developers or senior writers who do a lot of coding on the side. They generally practice docs-as-code, write novel content with only technical reviews as input (instead of editing content written by the developers), and also serve as QA and beta testers. Organizations often rely on these kinds of writers as the first users who aren't internal developers for new features, and they can be trusted to explore the bounds and edge cases of a new feature all on their own, with only occasional questions and meetups with engineering. They also frequently hack on documentation frameworks, writing extensions and layers on top of sphinx, docusaurus, markdocs, etc. They make near-developer salaries, sometimes even more.
As we lose testers and QA, and engineering organizations endure more and more hiring freezes, the latter class of technical folks become more and more valuable. It'll be interesting to see where the industry goes over the next few years. I'm tempted to say that docs-as-code scales better than collaborating on Google Docs, but who knows?
This article, unfortunately, is completely targeted at the traditional class of technical writers. See their recommendation on running your own blog:
The first step in creating your own blog is deciding on a
content management system or CMS that will help you maintain
your blog posts in one place without having to worry about
technicalities like formatting HTML code or writing css or
get busy with the back-end. You can start with any of the
following: WordPress, Wix, Ghost, Squarespace, Strapi or Sanity
Besides the fact that the first sentence is so long, rambly, and has enough structural issues that I don't believe a competent technical writer would ever craft it... this seems really close-minded to me. I personally use Jekyll and GitHub Pages for my personal blog, so I don't have any CMS besides a GitHub repo. If you're currently a developer, I recommend that approach -- it's closest to the docs-as-code documentation approach, too. Additionally, this quote commits the sin of conflating "using a CMS" with "writing posts in something other than HTML". Hopefully non-technical folks interested in technical writing don't get too confused by it.
Thanks for the suggestion of Jekyll + GitHub Pages. I'm looking forward to testing it as I'm currently in the process of starting my personal blog.
Q: Do you have any recommendations for the writing part as well? Most of the decent guides I could find (there's so much SEO spam in the space it's incredible!) are centered around fiction or general book writing instead of blogs, and I find most of them to be rather shallow.
For example, I feel like a blog post that shows how the editing process works with explanations on why certain phrases were deleted or rewritten could do wonders to my writing because as a non-native English speaker and "technical technical writer" I tend towards over-explaining myself with long phrases.
As another "technical technical writer," I have one recommendation: find a copy editor. I built up my writing skills by jumping headfirst into a technical writing gig and writing a hell of a lot of documentation. You can learn a lot from style guides and self-editing, but the fastest way to ramp up will always be the apprentice model. If you do end up trying out GitHub Pages and Jekyll, feel free to reach out to me for a copy edit on a blog post PR! I'd be more than happy to give some tips and pass on some knowledge.
An easier goal: use a tool like Hemingway to assess the readability of your writing. Aim for Grade 6 writing level, and clean up any sections of your writing that raise complaints from Hemingway. Eventually you'll start writing at that level by default as you rewire your brain to eliminate the wordiness.
“If you want to be a writer, you must do two things above all others: read a lot and write a lot. There's no way around these two things that I'm aware of, no shortcut.” -Stephen King
To build domain expertise, embed yourself wherever that knowledge is. For technical writing that's where engineers are writing code, product managers are creating functional specs, and support engineers are filing bugs/enhancements. The more embedded you are, the bigger an authority you become with your writing.
For me, the #1 skill here is having technical ability to actually use the product you're writing about. Like, don't just read about the product and do some write up -- you need to actually use it. Keep a list of questions or things that confuse you while learning since these will confuse other people too -- get answers to those questions. The reason, sounds so simple, is that most technical writing is marketing crap. It's easy to spot too. We live in a world that is flooded with SEO articles and technical people are starved for real technical content.
I have worked in this field and that's my experience. Here's my website https://sysadmincasts.com/ as proof. I work at a tech company and write blogs, create demo videos, and stuff like that for a very technical product. Happy to answer any questions. Also, comp can be pretty good like 3x+ what that are talking about in that blog if you are good. The job postings for this are normally something like "technical writer" or "technical marketing engineer".
This article seems to be based on second- and third-hand information rather than personal experience. I agree with others that it seems at least partially AI-generated.
If you're a software developer interested in working as a technical writer, I think the better resource is Writing for Software Developers by Philip Kiely.[0]
The title makes it sound like a book on technique, but it's more about the business of writing and finding freelance jobs writing tutorials and technical walkthroughs. Philip wrote it early in his career, but he had several years of professional experience as a technical writer already, which seems not to be true of OP.
Philip also maintains Who Pays Technical Writers,[1] a resource I'd trust for market rates more than any listed in TFA.
Having been in the content biz[1] for two decades now, I'll chip in my two cents: domain knowledge is king. What does this mean? You have to know how to use the product, or you need to bring some good knowledge about how the product works.
The tools you can learn, because they're going to be different everywhere, even if they're using the same "spec".
This industry has a set of "Industry Standard" tools that have been, in general (for the last fifteen years or so), a hot garbage fire. An awful lot of advice is given to get good at Tool X. That'll unlock the World of Tech Writing for you! Just plunk down a few thousand dollars, and you can be Enterprise Ready[2].
No. Far more important, if you want to get schooled on tools, is to learn the formals of Semantics, Change Management, Config Management, Computational Linguistics, and Systems Engineering. A lot of specs written in this field are obviously written from a non-technical perspective, and it implodes pubs departments right and left. With the theory, you can spot these traps before they trap you and your entire team.
[1] Admittedly in hard industries
[2] Just ignore the fact that the vendor is tied to a particular program, and when the program inevitably goes to its final reward your multi-million dollar system will have its support evaporate like morning dew.
10 comments
[ 2.0 ms ] story [ 29.5 ms ] threadIt's worth noting that technical writing is basically two professions wrapped up into one:
- On one hand, there are traditional technical writers; folks with next to no coding skills who frequently edit technical content written by others. These individuals typically use a CMS to produce content (since they have very few technical skills), use Google Docs or Word to edit and create content, and make money in the range indicated by the article.
- On the other hand, you'll find, er, "technical technical writers." These are typically former developers or senior writers who do a lot of coding on the side. They generally practice docs-as-code, write novel content with only technical reviews as input (instead of editing content written by the developers), and also serve as QA and beta testers. Organizations often rely on these kinds of writers as the first users who aren't internal developers for new features, and they can be trusted to explore the bounds and edge cases of a new feature all on their own, with only occasional questions and meetups with engineering. They also frequently hack on documentation frameworks, writing extensions and layers on top of sphinx, docusaurus, markdocs, etc. They make near-developer salaries, sometimes even more.
As we lose testers and QA, and engineering organizations endure more and more hiring freezes, the latter class of technical folks become more and more valuable. It'll be interesting to see where the industry goes over the next few years. I'm tempted to say that docs-as-code scales better than collaborating on Google Docs, but who knows?
This article, unfortunately, is completely targeted at the traditional class of technical writers. See their recommendation on running your own blog:
Besides the fact that the first sentence is so long, rambly, and has enough structural issues that I don't believe a competent technical writer would ever craft it... this seems really close-minded to me. I personally use Jekyll and GitHub Pages for my personal blog, so I don't have any CMS besides a GitHub repo. If you're currently a developer, I recommend that approach -- it's closest to the docs-as-code documentation approach, too. Additionally, this quote commits the sin of conflating "using a CMS" with "writing posts in something other than HTML". Hopefully non-technical folks interested in technical writing don't get too confused by it.I'm a "technical technical writer". Went from software development to writing, by starting a personal blog.
Works pretty well and I was (at least until now) not impacted negatively by global events of the last years.
Q: Do you have any recommendations for the writing part as well? Most of the decent guides I could find (there's so much SEO spam in the space it's incredible!) are centered around fiction or general book writing instead of blogs, and I find most of them to be rather shallow.
For example, I feel like a blog post that shows how the editing process works with explanations on why certain phrases were deleted or rewritten could do wonders to my writing because as a non-native English speaker and "technical technical writer" I tend towards over-explaining myself with long phrases.
An easier goal: use a tool like Hemingway to assess the readability of your writing. Aim for Grade 6 writing level, and clean up any sections of your writing that raise complaints from Hemingway. Eventually you'll start writing at that level by default as you rewire your brain to eliminate the wordiness.
“If you want to be a writer, you must do two things above all others: read a lot and write a lot. There's no way around these two things that I'm aware of, no shortcut.” -Stephen King
To build domain expertise, embed yourself wherever that knowledge is. For technical writing that's where engineers are writing code, product managers are creating functional specs, and support engineers are filing bugs/enhancements. The more embedded you are, the bigger an authority you become with your writing.
1. Read a lot 2. Write a lot 3. Write to provide your readers value
Writing is not to communicate "I'm smart", "I'm interesting", "I'm cool". Write to provide value to a specific community of readers.
I have worked in this field and that's my experience. Here's my website https://sysadmincasts.com/ as proof. I work at a tech company and write blogs, create demo videos, and stuff like that for a very technical product. Happy to answer any questions. Also, comp can be pretty good like 3x+ what that are talking about in that blog if you are good. The job postings for this are normally something like "technical writer" or "technical marketing engineer".
If you're a software developer interested in working as a technical writer, I think the better resource is Writing for Software Developers by Philip Kiely.[0]
The title makes it sound like a book on technique, but it's more about the business of writing and finding freelance jobs writing tutorials and technical walkthroughs. Philip wrote it early in his career, but he had several years of professional experience as a technical writer already, which seems not to be true of OP.
Philip also maintains Who Pays Technical Writers,[1] a resource I'd trust for market rates more than any listed in TFA.
[0] https://philipkiely.com/wfsd/
[1] https://whopaystechnicalwriters.com/
Having been in the content biz[1] for two decades now, I'll chip in my two cents: domain knowledge is king. What does this mean? You have to know how to use the product, or you need to bring some good knowledge about how the product works.
The tools you can learn, because they're going to be different everywhere, even if they're using the same "spec".
This industry has a set of "Industry Standard" tools that have been, in general (for the last fifteen years or so), a hot garbage fire. An awful lot of advice is given to get good at Tool X. That'll unlock the World of Tech Writing for you! Just plunk down a few thousand dollars, and you can be Enterprise Ready[2].
No. Far more important, if you want to get schooled on tools, is to learn the formals of Semantics, Change Management, Config Management, Computational Linguistics, and Systems Engineering. A lot of specs written in this field are obviously written from a non-technical perspective, and it implodes pubs departments right and left. With the theory, you can spot these traps before they trap you and your entire team.
[1] Admittedly in hard industries
[2] Just ignore the fact that the vendor is tied to a particular program, and when the program inevitably goes to its final reward your multi-million dollar system will have its support evaporate like morning dew.