My favourite (technical) technical writing resources

There are a number of really useful blogs and sites around these days which will be of interest to the more technical type of technical writer – I thought it would be useful to create and maintain my own list of links to my favourites.

The list is not meant to be exhaustive, and doesn’t include many standard tomes (Chicago Manual of Style, etc.) – it’s really just a list of things I really like and which relate to how I see the field developing. I’ll update this page as I come across other sites I like.

• I’d rather be writing  Tom Johnson’s excellent blog contains many articles and also short courses, as well as many podcasts (I’ve found that listening to the podcasts while commuting is a good way keep up with technical writing trends). Tom’s based in Silicon Valley and has worked for several of the big players. His podcasts include recordings of some Bay Area meet-ups, which provide interesting insights.
• hack.write()  Another interesting blog, this one tends to focus on developer documentation, using “documentation as code” approaches. It’s currently quite a new blog with only a few pages, but seems to be updated very regularly (at least for now).
• Write the Docs (WTD)  The Write the Docs group is a really good way to keep up with what’s going on. The WTD slack channel is full of some very knowledgeable folk, with a lot of useful discussion. There are conferences and meetups. I find WTD to be more interesting than other groups like STC (and it’s free and open to anyone). Again, there is a slight slant with WTD toward developer docs, API docs, docs-as-code, static site generators (especially Sphinx and to some extent Jekyll), open source, use of GitHub, and so on.
• Modern Technical Writing  I think everyone involved in software documentation (especially developer facing documentation) should read this short book. It’s only a couple of quid for the e-book on Amazon. I wrote a review here.
• Elegant Documentation Principles  Nice GitHub project (no code, just the readme file containing the text you see when you visit the repo) with some principles for good tech writing. I like how the author has taken some principles from software development and attempted to come up with similar ones for good technical writing.
• Every Page is Page One  Mark Baker’s longstanding blog (named after his book) is strong on topic based authoring / single sourcing, but also other issues, including lightweight markup.
• StaticGen  This site is a nice resource (provided by Netlify, a hosting service) giving a fairly comprehensive list of the static site generator tools that are available. It’s built from a public GitHub project so you can suggest changes if you know of something missing. There’s a link to a matching list of headless-CMS systems too.
• Beautiful Docs  This is another GitHub readme, with a list of nice examples of great documentation, a list of useful tools, and a list of some other resources about tech writing. The project owner accepts contributions, so you can fork the project and send a pull request with your suggestions for any other good examples.
• On docs, learning to code, and life  Jennifer Rondeau’s blog has a few nice entries about API docs writing and related issues. I especially like the rant about why technical writers should stop talking about “Subject Matter Experts” and become part of the team, and her suggestions on learning API technology (don’t rely on reading about how to document APIs, instead learn about APIs). Other topics include problems with Swagger, why API docs are important, and so on. Worth a read.
• AgileDocumentation  This blog by Rob Woodgate, a UK based technical writer, has some good thoughts on how tech writing (and tech writers) fit in with the Agile process. For example he considers the question of should documentation be in the definition of done? (his answer is, it depends). Much of this blog is relevant to anyone writing software documentation in an organisation using Agile development process, whether or not the tech writer is a “technical technical writer” producing developer facing docs. However it seems to me that one of the features of Agile (tech writers are part of the team, not separate) is to an extent a reflection of (or perhaps a driver of) the “documentation as code” movement (tech writers using the same tools and processes as software developers, because code and docs are both software).
• Documentation as code  Because this term has become quite trendy just recently, I thought I’d look up where it came from, and I came across this slideshow by Evan Goer from 2013 (Evan’s a programmer with an interest in documentation). The term seems to have been picked up by others (though I am prepared to believe that he got the term from someone else originally). Anyway, what it means, simply, is for tech writers to use tools and processes that software developers have already got, rather than re-invent wheels. Or, as Evan puts it; “The radical notion that documentation is part of your project, just like your source code and build scripts and unit tests and everything else”. Most obviously, docs should be in version control, just like other assets (I’ve been doing this for twenty years so no argument from me).
• Google Developer Documentation Style Guide – Google recently made their style guide available to the public, and it contains a lot of sensible advice, including the caveat that it is only for guidance. Obviously the first rule to break the one about using American spelling…