3 ms·
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
by dont__panic 4y ago
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.
- k__ 4y agoGood points! 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.
- bot347851834 4y agoThanks 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.
- vanilla_nut 4y agoAs 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.