As developers, not only do we need to know how to communicate our code, we also need to understand how to create written and technical documentation to ensure our meaning, decisions, and processes are understood. This technical writing happens as documentation, inter-team communication--communication between different teams--and even blog posts. But what if you’ve never been trained in technical communication? How can you get started in technical writing?
Key terms
Technical Writing: The process of writing about complex concepts for a specific audience.
Audience: Who you are writing for or to.
Jargon: Often technical in nature, words that your wider audience might not easily understand. For example, I might use ASR if I’m working on a Deepgram post. Outside of a specific technical audience, this won’t mean much. Instead, I should write, “Automated Speech Recognition (ASR) uses Machine Learning to take speech and create text.”
Audience
Let’s start with a checklist. Think about your audience and then answer the following questions:
- How will that affect your word choice and tone?
- What do your readers need to know?
- How much information is enough?
- Put yourself in the reader’s position. What do you need and want?
- How can you make it clear, relevant, and provide practical examples?
- Will using videos, images, or code samples benefit your audience’s understanding?
After answering these questions, think about your topic and how you'll develop it as a blog post. This will help you determine how and when to avoid or explain jargon. Is your audience learning to code? Are they looking for advanced applications of a concept? How can you support them in their learning journey--because anyone who’s reading a blog post is on a learning journey, just at different levels.
Start writing down ideas to help you to create an outline and eventually fill your post.
Types of Technical Writing
In this post, we’re focusing on technical writing, but we’re going to break that down into three categories: informational, instructional, and persuasive. As tech writers, we experience a little bit of these in each post. It’s okay to see the overlap. In fact, if you recognize it, you’ll be a more effective writer.
Informational: With informational writing, your primary purpose is to give information. You might have a post, for example, “Explain it to me like I’m 5: Automatic Speech Recognition” or “Five ways to use Deepgram to increase accessibility in your school.” Your writing is factual, provides objective information, and can bring in external resources to provide adequate information to your reader.
Instructional: Instructional writing, at its heart, is writing to teach. You want your reader to learn based on what you’ve written. This means you need to provide clear instructions, examples, and explanations. And as a result of reading your instructional writing, your readers should be able to follow along and complete a task with little to no questions. Try to anticipate the questions of the reader. You don’t have to answer all of their questions, but consider a combination of answering questions, linking to answers, and/or pointing out that there are topics that you haven’t covered in your post.
Persuasive: In this form of writing, you’re trying to convince the reader of something. Maybe you want them to choose one technology or product over another. Maybe you’re asking them to come back to read your next blog post. With persuasive writing, you’re working towards asking your reader to decide on something.
Structure & Content
Whatever type of writing you’re working on, having a beginning, middle, and end matters. In the beginning--often referred to as the introduction--you’re giving your reader a roadmap for what to expect. Are you going to teach them something, convince them to use a specific technology, or break down a concept? Your reader should never have to guess where you're going in your post.
The middle of your writing should provide supporting ideas for your topic and give examples. If you’re writing about Speech-to-Text, you should give a definition, examples, and explanations of what that means. Each paragraph--or chunk of text--should focus on one idea, connecting the ideas in the paragraphs around it.
If you’re taking an instructional point of view to show how to use Deepgram in the classroom, you might cite Kevin’s Classroom Captioner post, provide another example, and give the readers both step-by-step instructions as well as an explanation of why you’re doing those things. If you’re referring to code, it’s always better to include code samples. Two great ways to do that are: Ray.so and Carbon. In Dev.to, you can also use markdown syntax with single backticks--those are the ones to the left of the 1 on the keyboard--or triple backticks for longer code samples.
Proofreading
Even if your code is perfect, you’re not done. Proofreading is one of those things that takes time to get right. I highly recommend adding the free grammarly extension to your chrome browser.
Some other strategies I like include:
- Read your writing aloud--hey, you can even have Deepgram transcribe that for you to read how you sound!
- Read your paragraphs from the conclusion to the introduction,
- Look at your coding samples to see if they clearly explain the meaning you want to convey.
Technical writing should be clear, have a purpose, and share examples that allow for understanding and application if necessary. I’ve heard many people say that technical writing is boring, but that doesn’t have to be the case. It’s interesting if you make it interesting. Stay tuned for the next post in this series where we'll go into some strategies for creating engaging content.
Discussion (0)