7 Tips on Writing Good Technical Content

Technical writing fills the gap between the technology experts and general users of the technologies. Writing a good piece of content is an art that can affect the market presence of the product/service as well.

Usually, any piece of technical content has the following target.

Target: Create a substantially different article and 10X better than what is currently ranking. This article summarizes the key tips on achieving this target.

1. Decide on Content Idea and Size

• Look at competing articles of the interested domain on top of google search before writing. ( search Google with target location of the audience, e.g., use I Search From)
• Word Count - High word count is a good idea. Get the average word count in your top 5 competing articles and double it. 
• Write to an 8th Grader - Don’t create your content only for experts. (i.e., easy to read and understandable for the average person )
• Decide on the audience. e.g., Beginners, Developers, Architects, etc.
• Limit your document to only one goal. If not, break into multiple articles. 
• Decide on the type of content. 

  • Getting started documentation - This is to help users with getting up and running systems and also to build trust with your users. Some examples are quickest explanations on the product/service, most straightforward steps to install and use, cool things users can do with product/service, etc.

  • Tutorials - A procedure that teaches users how to achieve a specific goal. Ideally should contain less than 10 steps. They focus on learning.

  • How-to guide - This shows how users can solve actual business problems by performing specific steps with your service/product. They focus on implementing real-world code.

2. Know SEO Keywords and Include Them in the Content

• Search your keywords using some popular tool. e.g., Answer the Public Alternatives: KeywordTool.io, UberSuggest, Keyword Sheeter, Keyword Generator
• Include the possible keywords within the URL.
• Keyword positioning: Try to keep your main target keywords within the first 2 to 3 paragraphs and the second set of keywords in the rest of the content. Also, use relevant H1, H2, and H3 title tags with those keywords.
• Add trustworthy external links. See 7 External Linking Best Practices for SEO

3. Organize Content Properly

Write shorter paragraphs. Limit paragraphs to five sentences or fewer when possible. Short paragraphs are easier to read on mobile devices.  

Use headings that tell the story.

• Brief and Clear- Even without reading the paragraph, users should be able to get a high-level idea by reading the title. 
• Have unique headers for each section. 
• Be consistent on all the headers - Start with verbs, etc.

Use pattern interrupts to keep the reader engaged (i.e., multimedia, bullet points, numbered lists, influencer quotes)

Procedures - a sequential set of actions a reader takes to achieve the desired result.

• Should always use numbered lists - the readers understand the order of tasks
• At the start of the procedure, explain the desired goal - users understand what they are doing. 
• At the end of the procedure, add a way for the user to check that they performed it correctly. 

Lists - No exact order, but order it in a most helpful way to the user. Less than 10 items are preferred.

Callouts - a piece of information that your reader needs to know at that moment but that doesn’t fit with the flow of your content. E.g., Note, Warning, Info

Refer to widely accepted style guides. E.g.,

• Microsoft Writing Style Guide
• Google Developer Documentation Style Guide

 4. Add Code Samples

• Documentation can contain two types of code samples: 

  • Executable: A runnable piece of code 

  • Explanatory: Not expected to be runnable. A block of code the reader can learn. 

• Wrap lines after some number of characters (Google’s style guide suggests 80)
• Use an ellipsis (...) to indicate some part of the code is not shared. 
• Write comments, explanatory texts, etc., when needed.
• Use proper formatting and syntax guidelines.   
• Add production-ready code.
• Try to store code in GitHub as files or Gists and add embed to the content. That will make sure the code is properly maintained and tested. 

5. Use Images and Media

• Instead of stock photos, custom images will be better.
• Try to have more media types and embed them into the content. (Images, graphics, screenshots, charts, videos, audio files, gifs, infographics).
• Use “alt” text as it is good for screen readers and search engines - add a description of the content of the image as if the image wasn’t there at all. Refer decision tree by w3schools. 
• Illustrate only one idea per diagram. E.g., one level of abstraction in a system, one process flow, or a particular piece of logic.
• Use an online color contrast checker to ensure the diagram and text are readable in a colored background.
• Publish images in SVG format. Those will scale well, and the reader can access and zoom in diagrams at any screen size.

6. Do Proper proofreading 

• Check the readability of the content. E.g.,  Readability Calculator - Target `Gunning Fog index: ` 8 or less.
• Check Grammer and Spelling - E.g. Grammarly
• Check all the links for validity.
• Cite and acknowledge sources

7. Promote the content

After your content goes live, it is important to inform about it the right audience.

• Use main social media to share your content - Twitter, LinkedIn, Facebook, etc.
• Submit content to platforms/publications that have their own audience of readers.
• Share outside of your network: such as groups and communities - Quora, Reddit, Hacker News, etc.
• Re-share the content after a few days/weeks with a different message.

References :

Docs for Developers by Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, Heidi Waterhouse

Unstoppable Content Formula

7 External Linking Best Practices for SEO