These top 5 technical writing resources help you build both your technical writing skills as well as your writing skills.
The “technical” is more important than the “writing”.Anonymous
This is a saying that is often passed down from experienced technical writers giving advice to beginners in the field—you probably have heard it yourself.
I remember giving such advice when an English major made a post on LinkedIn asking for advice on transitioning from fiction writing into technical writing.
To some extent, we agree with this point, and it is for no other reason than the increasing complexity of technology and the difficulty finding technical writers who could understand tech.
It is thus a simple law of demand and supply that employers will come to value writers with a background in technology more than writers from a writing background.
But not so fast.
An over-identification with this point of view could spell trouble too. It could become very misleading, it may also imply that writing skill is not needed, which is false.
What you must seek is a balance. You must prioritize both the “technical” aspect and the “writing” aspect of your craft.
Prioritizing your writing skills as much as your technical skills might make the difference between you and a sea of other technical writers who pay little to no attention to honing their writing skills.
So in this article, we will be sharing with you the top 5 technical writing resources that will help you take your technical writing skills to the next level, both the technical and the writing aspects of the technical writing craft.
These resources are specific to software documentation and everything about creating technical content for software products and technologies, which will strongly appeal to you as a software engineer doing technical writing.
So let’s dive in.
Top 5 Technical Writing Resources
Below are the top 5 technical writing resources you can use to hone your technical writing skills.
The contentre blog is a great resource for technical writers. It provides technical writers with tools, resources, webinars, and stories from other technical writers to you grow your technical writing career in one place.
Idratherbewriting means “I would rather be writing”. It is an interesting blog name.
Idratherbewriting is a blog owned by a thought leader, Tom Johnson, from the technical writing world.
His blog boasts of hundreds of blog posts about the craft of technical writing. Tom Johnson is perhaps one of the few technical writers who write about the technical writing craft itself. It is no surprise given he was an English major.
He is one of the many who successfully made a transition to technology in the early 2000s when technology hadn’t become as diverse as it is today.
One of the most distinct qualities of Tom Johnson’s blog is its API documentation course, which has helped train many beginners in technical writing and helped them successfully land jobs as technical writers with top companies of the world like Google and Amazon.
To cap it all, Tom Johnson’s API documentation course is completely free!
Tom Johnson’s API documentation course contains several sections that would help you hone different aspects of your technical writing skills—both the technical aspects and the writing aspects.
Let’s look at a few of them:
Documentation of API Endpoints
This is one of the core tasks of the technical writing profession, and this course will help you master this task.
This section occupies the first five sections of Tom Johnson’s API documentation course.
In the first section, Tom Johnson takes you through an introduction to REST APIs to lay some foundation, then following it up with the second section that takes you through using API like a developer. This section provides you with practical knowledge of how software engineers use APIs.
The third section teaches how to document API endpoints. I particularly like this section as it gives you a vivid breakdown of how your API reference should appear: the parts such as resource description, requests and endpoints, parameters, and response and schema, that you must include in your API reference guide when creating one from scratch.
The last two sections take you through OpenAPI, an API documentation tool for generating API reference guides.
As a software engineer, this might be second nature to you. You are used to reading and implementing code tutorials, so creating one might be a no-brainer.
However, creating code tutorials is a skill and like every skill, it can be honed. It can be trained to be even better. So do drop into this section in the course. You might pick up one or two things that would come in handy when writing your code tutorials.
The Writing Process
This is the section that handles the writing aspect of the technical writing craft. This section covers the entire process of creating documentation from scratch when working as an in-house technical writer creating documentation for a tech product.
Freelance technical writers would also find it useful especially when they have to deal with creating entire documentation (product and API documentation) for their clients.
It covers the entire writing process from planning, to information gathering, to writing, to reviewing, and lastly, publishing documentation.
There are other sections such as Conceptual topics in API docs and Native Library APIs that are also worth checking out. It is a great course you will find very interesting.
The Good Docs Project
The Good Docs Project was started by a community of technical writers, developers, UX designers, and more who work together to make software documentation better.
While you can check out their website, the Good Docs Project resource is housed on GitHub. The resource is packed with templates and guides that would help you produce better documentation.
The resource covers a wider gamut of technical content deliverables that range from getting started, installation, and product overviews, to tutorials, how-tos, and reference guides.
Furthermore, the resource provides a breakdown of each technical content deliverable, providing you with a template that you can easily adapt and tweak to suit your purpose.
You should check it out.
The Diátaxis Framework
Diátaxis is described as a systematic framework for technical documentation authoring. The Diátaxis framework is a documentation framework developed by Daniele Procida, a lead technical writer and Head of Engineering at Cononical.
The framework approaches understanding and creating technical documentation deliverables from a unique point of view.
It identifies four modes of documentation: tutorials, how-to guides, technical references, and explanations.
Each of these modes (or types) is designed to answer to different user needs, fulfill different purposes and require different approaches to their creation.
One of the things you will learn studying the Diátaxis framework is the difference between tutorials (learning-oriented) and how-tos (problem-oriented), both of which are often confused together or even thought to mean the same thing. It will help you understand the scenario where either of them is best for technical content creation.
This also applies to understanding the difference between explanation (understanding-oriented) and reference (information-oriented). They can be easily confused together too.
In summary, the Diataxis framework is a framework that would help you ground a strong theoretical knowledge and help you develop a sound way of thinking about technical writing.
Expert Support is a technical writing agency that creates technical documentation for software products.
In addition to the Idratherbewriting of Tom Johnson, Expert Support constitutes the few places where the technical writing craft is written about.
The difference between them is that while with Tom Johnson’s Idratherbewriting, you will get to read more content on the lifestyle and the daily struggles of being a technical writer, Expert Support’s blog will expose you more to the business side of technical writing, where you learn how to handle the relationship with clients, understand their documentation needs, plan, design, and deliver documentation, e.t.c.
This will be a great resource for freelance technical writers.
Expert Support also hires and trains technical writers who work with them to create technical documentation materials for their clients.
Passo is a technical writing blog owned by Fabrizio Ferri Benedetti.
It hosts the owner’s experience as a technical writer–it is very similar to Tom Johnson’s blog, especially the aspects of his blog that talk more about his lifestyle and experience.
This provides you with added insights into the technical writing craft as you learn from the experience and expertise of Fabrizio.
So there you have it. Top 5 technical writing resources to help you hone your technical writing skills.
To get the best from each resource, pour over each content you interact with more than once. Then, do ensure you put into practice what you learn. Knowledge without practice is useless.
Do leave a comment if you find the content useful.