Part 1
Technical Writing: Your Engineering Superpower
What Is Technical Writing?
You’re already a technical writer, so learn how to do it well and unlock your engineering superpower!
The phrase “technical writing” usually brings a few things to mind — in particular technical blogs and programming books. But your everyday life as a developer is actually full of technical writing. Every time you open a pull request, write a GitHub issue or Jira ticket, author a technical design doc, or even Slack a teammate for help with a tricky bug, you’re doing technical writing. Your job as a dev isn’t just to write code, it’s also to write about code. By sharpening your technical writing skills, you’ll magnify your impact on your team and become a better, more effective engineer.
In Part I of this two-part series, we’ll talk about what technical writing is and why it matters to you. Then, join me in Part II to learn how to do technical writing well. Let’s get started!
What Is Technical Writing?
Technical writing describes any written communication about code. That includes not only a blog post on how to mock HTTP calls in Golang tests, or a book on learning to program Phoenix LiveView, but also the writing you do every day as a developer.
If you’ve ever so much as sent a Slack message to a friend or colleague asking for help with a programming problem, congratulations! You’re a technical writer! 🎉
Technical writing is everywhere in your professional life as an engineer, and it’s a big part of your job whether you realize it or not. Pull requests, GitHub issues, project plans and technical design docs, Stack Overflow questions, and more all require you to communicate about code, in writing.
With that in mind, it’s not hard to see why sharpening your technical writing skills will help you become a better engineer and a better teammate. Let’s dig into the different types of technical writing you’re likely to encounter now, and why each type matters.
Why Technical Writing Matters to You
Let’s start with what is perhaps the most obvious type of technical writing — blogging.
Publishing a Technical Blog
When you write technical blog posts on any programming topic, you’re creating a resource that will help some future dev solve a problem — and that future dev just might be you! I frequently reference old blog posts I wrote years ago when I find myself facing the same challenge.
Further, by creating resources that will help other developers along their own educational and professional journeys, you are contributing to a supportive and nurturing programming community. So often, I’ve heard people say that they can’t blog because they don’t have anything to write about — what they’re learning is too easy or too basic to warrant a blog post. This line of thinking ignores the reality of the many other people who are learning to code. There are so many people out there in all different phases of their careers as engineers — maybe your post will help someone who is just getting started, or maybe it will help someone who is an experienced engineer diving into a new language or framework. The more resources across all levels we contribute, the more accessible learning becomes, and the more our community grows stronger and more diverse.
Let’s dive into some of the other forms of technical writing you encounter as a developer now, and talk about the impact they have on your life as a dev.
Shipping Pull Requests
The most common workflow on an engineering team is that of opening a pull request (PR) to merge new code into a codebase. Your PRs can get merged only if your teammates can review them. They can review them only if they know what problem the code solves and how. Your PR description (and technical writing) comes in here.
A well-written PR description tells the reviewer:
- What the code does
- Why it’s needed
- How it works
- How it’s been tested
Your PR description gives the reviewer the tools and context they need to meaningfully review your PR. Without a strong description, your reviewers are more likely to provide a review that doesn’t engage deeply with the code and therefore misses bugs and edge cases, or a review that focuses too much on the nitty-gritty details and misses the big picture.
So, to get productive and meaningful PR reviews that result in robust code, and to ship your PRs in a timely manner, write a good description. We’ll talk more about what a good PR description looks like in part two of this article. For now, let’s move on to the impact of another type of technical writing: tickets.
Writing GitHub Issues or Jira Tickets
The exact flavor of project management tools varies widely from team to team and organization to organization. Maybe your team uses GitHub Issues, or Jira tickets, or Pivotal tickets, or Trello cards. Regardless of the exact tool, all of these project management strategies use an entity (ticket, issue, card) to describe, in writing, some new programming work that your team needs to deliver.
Anyone who has had the misfortune of pulling a ticket with a vague description and limited detail knows just how important it is to write tickets well. GitHub Issues and Jira tickets can get delivered only if the developer who picks them up can understand what works needs to be done. A well-written ticket describes what needs to be built and why. As an engineer, you will find yourself responsible for writing these tickets at least sometimes. And even if you don’t, a sharp ability to distinguish a well-written ticket from a poorly written one will help you deliver your work quickly and easily.
Writing Technical Design and Project Docs
Your great idea to solve X technical problem or to deliver Y feature-set won’t get implemented if you don’t communicate well. You will find yourself responsible for writing technical design docs and project proposals over the course of your career, so this type of document is critical to master.
Your organization may have different names and procedures for these documents, but most teams outline long-term projects and detail technical design decisions that have a big scope or impact. These documents are important because they communicate technical design decisions to your team and beyond, and you’ll use them to help your team deliver on complex projects.
Getting Help
Your request for help from a colleague over Slack, or through a Stack Overflow post, is only as successful as it is well-written.
No one can help you if they don’t understand what the problem is, and it’s up to you to communicate the issue.
So, a well-written request for help is what makes the difference between even more hours of frustrated debugging, or a swift resolution with the help of a colleague.
Next Time
That’s it for Part 1 of this two-part series on technical writing. Now that you’re able to recognize varieties of technical writing in your daily life as a dev, and understand the big impact that technical writing has on your success as an engineer, you’re ready to learn how to do it well. Join me in Part II for a look at how you can successfully tackle each and every type of technical writing:
If you enjoyed this article, check out this book from Sophie DeBenedetto and Bruce Tate, published by The Pragmatic Bookshelf:
You can save 35% on the ebook version of Programming Phoenix Liveview by entering promo code superpower_35 at checkout. The code is good through July 30. Promo codes are not valid on prior purchases.
You might also enjoy Technical Blogging by Antonio Cangiano:
Read on Medium.
