Technical Writing: Ultimate Beginners Guide

Derrick Mwiti
Derrick Mwiti

Table of Contents

I have created technical content for various companies over the last 5 years.

Educating developers is how technology companies use to grow their communities. Developers hate being sold to, so this is the best way to get developers to use a company's product. The product should solve a problem for the developer to convince them to try it.

Companies also need content to create awareness about the company and its offering. At some point, the developer may be in a role where they need the enterprise version of the company's offering and guess which product they will recommend– the one they have been using. This is where technical writing comes in.

Who is a technical writer?

A technical writer is a person who educates developers by simplifying various technical concepts. The aim is to educate developers on various topics through technical documentation, blog posts, guides, and tutorials. This content helps establish the company as an expert in their domain.

Technical writers are not the only people who write technical content. Other roles that involve writing technical content include:

  • Developer relations
  • Developer advocate
  • Technical documentation manager
  • Developer educator

Why write technical content

The current demand for technical content makes technical writing a valuable skill in your repertoire. Whether you want to build a career in a technical writing role or not, writing is an important skill for various reasons:

  • Gain a thorough understanding of the technical concepts
  • Help developers who are a few steps behind you understand the technical concepts
  • Build a personal brand in the topics you are writing about
  • Be part of a community where you can also get assistance

Writing also prepares you for other opportunities in the future, for instance, authoring books. With a library of content, creating a digital product in the future becomes easier than starting from scratch. You are also practicing for potential job opportunities in the future.

Technical writing skills

Whether you want to build a technical writing career or write on the side, there are critical skills that you have to master:

  • Coming up with ideas for technical content
  • Researching the topics from various sources, such as books
  • Tactics and techniques for promoting your work
  • Formatting your work to make it skimmable
  • SEO tactics that will enable your posts to rank on Google
  • Ability to pitch companies to get technical writing work

Parts of a technical article

A technical article is made up of 3 key parts:

  • Introduction
  • Body
  • Conclusion

Let's explore some ideas of how to create great intros and conclusions.

Crafting a great introduction

Each technical article you write will solve a specific problem for the reader. Here's a framework I use for writing introductions.

Let's look at it through the lens of the Accelerate Hugging Face Inference Endpoints with DeepSparse article.

  • What is the problem? Handling infrastructure
  • Who is facing the problem? Technical experts
  • What is the consequence of this problem? Long deployment times that impact the iteration rate on your model’s journey to production
  • What is the solution? Hugging Face 🤗 Inference Endpoints
  • Why should you use this solution? Generates an inference endpoint in minutes
  • Why is the solution better than the alternatives? You don’t have to manage servers
  • What the article will cover. How to quickly deploy a sentiment analysis pipeline as a Hugging Face Inference Endpoint
  • Expected results after using this solution. Implied above

I would then divide these points into 3 paragraphs:

Paragraph 1: The problem. Who is facing the problem? What is the consequence of this problem?

Paragraph 2: The solution. Why is the solution better than the alternatives?

Paragraph 3: What will this article cover? Expected results after using this solution.

The body

The body is where you cover the meat of the article. Use heading and subheading to separate different ideas. If the article is a how-to guide, you can use headings that look like this:

  • Step 1: Installing Git LFS
  • Step 2: Install the package
  • Step 3: Downloading Deployment Files from the SparseZoo
  • Step 4: Adding DeepSparse Pipeline to the Endpoint Handler

Crafting a great conclusion

The conclusion covers the summary of the article with a call to action.

Here is a framework for crafting a great outro from the same article used above:

  • What was covered in the article? Showed how easy it is to set up an HTTP endpoint using the Hugging Face Inference Endpoints platform with DeepSparse
  • Advantages of using the solution proposed in the article. Dramatic performance improvement and cost reduction.
  • Call to action and next steps. View GitHub and join the Slack community

Finding and validating ideas

I get messages from people about what they should write about. When starting, writing what you are currently doing will be easier. For instance, if you are taking a course on Pandas, you can write articles about that. However, since these are technical concepts, you'll have to spend time learning a topic if you are not already familiar with it. Here are some more ideas for finding and validating ideas.

Document a project

You might already have content to write about without knowing it. Look at the projects you are currently working on or projects you have done in the past. The beauty of this is that the content is ready, and the only thing left is to document it.

Other blogs

Other technical blogs can also inspire what to write. For instance, look at other web development or data science blogs. If you find an interesting topic, you can research it and write about it. If you use content from that blog, you should reference it.

Books

You can also get ideas from technical books you have read or are currently reading. Mentioning the author when promoting the content can also help you reach a wider audience.

Reddit

Writing something unique about a popular topic leads to many reads on your articles. Reddit is one great place for sourcing popular technical topics. Visit the subreddit related to the topic you want to write about and filter for top posts.

Writing about a popular topic can get your content trending, especially if you approach it from a different angle. For instance, chatGPT is a hot topic at the moment.

Technical writing editing checklist

When you are done writing, let the words sit for a few minutes, then come back to editing with a new perspective. Don't try to edit as your write; it will slow you down. Write to the end and treat that as a first draft. Next, edit that draft to make it better.

Here is what my current editing checklist looks like.

Grammar check

Use Grammarly to check for grammar and typos.

Check with style guide; if provided

Check the article with the provided style guide, for example:

  • Capitalize words in the title and subheadings
  • Start heading and subheading with action verbs
  • Start list items with a word that ends with s or ing whenever possible
  • Proper abbreviation formatting, e.g., regions of interest (RoIs)
  • No fullstop at end of list

Remove unnecessary words

Some words in a sentence can be removed, and the sentence will still be understandable. For example:

  • You will be able to/ You can
  • You have to install the package/ Install the package
  • You should be sure / Ensure
  • Which is
  • That is
  • will
  • Came up with / Developed
  • You can use / Use
  • Enables the generation/ Generates

Maintain consistency

Maintain consistency in naming. For example, if you start with ResNet50, use it throughout the post. Don’t switch between ResNet-50, Res-Net50, etc

Active voice

Write in active voice using the first person “You”.

Check “of” and “in” usage

Sometimes a statement can be made less wordy by removing of and in. For instance:

  • reduces the cost of production / reduces production cost
  • ensuring optimal usage of resource / ensuring optimal resource usage

In-line style

Check for proper in-line styling:

  • Bold important words or phrases
  • Use monospace font for in-line code

Check for repetition

Delete or rewrite repeated information.

Avoid large walls of text

Use short sentences (3-5 sentences) to make the content skimmable

Use meaningful words when cross-referencing

Bad: To learn more about Keras check this blog.

Bad: To learn more about Keras click here.

Recommended: To learn more about Keras, check the Quickstart guide.

Here are some more technical writing resources:

Google Style Guide

Microsoft Style Guide

GitLab Style Guide

Laws of technical writing

Technical writing principles can accelerate your career as a technical writer. Here are some principles to keep in mind:

  • Don't start a blog. When starting, you need to publish in places where you can be found. A personal blog is not that place. Instead, publish in places that already have readers, such as Medium.com. Apart from the factor that publications with a reader base will recommend your articles to their readers, you also stand a better chance of being found by people looking for writers.
  • Don't be salesy. Developers can smell sales copy from a mile away. Don't try to sell developers on the company's offerings. Instead, teach them and let them decide whether they will use the product.
  • Go deep. Don't skim over technical concepts. Explain them such that the reader understands them in-depth.
  • Visualization is king. Show, don’t tell. Use GIFs, screenshots, and videos to explain complex topics. It is much easier to understand a technical topic after looking at a visual illustration.
  • Treat your ideas like cattle, not pets. Don't be attached to your article ideas. If you are attached, you will be disappointed if a certain article doesn't perform as well as you thought. Instead, focus on churning out as much high-quality content as possible.
  • Track views and repeat well-performing ideas. Track how your articles perform and double down on what works. For instance, you can create more MLOps content if you realize such articles get more readership.
  • Use plain English. Avoid Jargon. Write at the level of an 8th grader, no one wants to spend time googling words when reading an article.
  • Provide all assets. Developers like trying things for themselves. Provide all the assets they need to reproduce what they are learning.
  • Write for a specific developer. Know your developer. Writing for a specific audience dictates how you'll write the articles. For example, if you are writing for TensorFlow beginners, you have to explain the process of loading data, something you don't have to do when writing for advanced users.
  • Make your content skimmable. Avoid large walls of text. Write in short paragraphs that make it easy for the reader to skim and find what they are looking for. You can also make the content skimmable by writing clear headings and subheadings.
  • Hit publish. Your first pieces of content won't be the ones you are most proud of. Don't obsess with numerous editing iterations. Hit publish, you can always come back and edit the content in the future.
  • Consistency breeds consistency. The more you write, the more you write. Don't give up after publishing the first article. Keep writing if you want to keep writing.
  • Fact check. Since you are writing technical content, check that it's technically factual. You can do this by reading research papers or talking to experts on that topic.
  • Use transitions. Keep your content engaging by adding transitions from one section to the other.
  • Check your grammar. With free grammar tools such as Grammarly, it has never been easier to fix grammar issues in your writing. Articles with numerous grammatical issues and typos are hard to read, making this an important item to review in your technical articles.

Building a career in technical writing

Technical writing can lead to numerous opportunities, including getting full-time or freelance roles.

I am convinced you will get technical writing and other technical jobs faster if you consistently create content. Your content is like a silent resume on the internet. The content will work for you even when you are asleep.

Before you start applying for technical writing jobs, I recommend you first take these 5 steps:

  1. Pick 3-10 technical topics

2. Read and research these topics

3. Create 3-10 high-quality writing samples

4. Get an experienced writer to review them to ensure high-quality

5. Submit your work to publications with numerous readers on and off Medium

Link your LinkedIn profile on every article you write and wait for the LinkedIn DMs asking you if you can create content for companies.

Technical writing tools

You don't need any fancy equipment to create technical content. However, some tools can improve your writing experience and help you create engaging content.

Here are the tools I use:

  • Grammarly for checking typos and Grammar issues
  • TinyWow or ezgif.com to create GIFs from video
  • Canva for creating book covers and article feature images
  • Xnapper for taking beautiful screenshots
  • DaVinci Resolve to edit videos
  • Affinity Designer and Photo for simple designs
  • Google Docs for writing
  • Code blocks add-on for code formatting
  • Ghost for writing a personal blog

How to promote your technical content

Starting a blog is not advisable if you are starting your technical writing journey. However, you should write in a publication with a large following to get your name seen. These publications also promote your content to their readers. Some great examples are:

  • KDnuggets
  • Hashnode
  • Towards Data Science
  • Dev.to
  • Freecodecamp
  • GeekCulture on Medium

Start by writing on a personal Medium account because you are unlikely to get accepted into these publications without a few writing samples.

Final thoughts

To become a prolific technical writer, you must craft a routine for ideating, researching, and creating content. I suggest that you use the strategy below.


Whenever you're ready, there is 2 way I can help you:

If you're looking for a way to build a career while writing about data science and machine learning, I'd recommend starting with an affordable ebook:

Writing for Data Scientists: The exact path I followed to get technical work that pays between $250-$500 from machine learning companies such as Comet, Neptune, cnvrg, Paperspace, Layer, Neural Magic, Determined, Activeloop, and many more. Get your copy.

Data Science and Machine Learning Ebook: I offer numerous free and paid data science and machine learning ebooks to help you in your data science career. Check them out.

Technical Writing

Derrick Mwiti Twitter

Google Developer Expert - Machine Learning

Comments