technical-writing-template
A sample template for writing a technical article ๐ฆ
Template Headings
## Title
## Introduction
## Prerequisites
## Headings
## Conclusion
## Attributions
Title
As the name implies, this is the title of your article which describes what your article entails. Ensure to use title case here.
- What will a reader accomplish after reading your article?
- Include the goal of the article in the title.
- (Optional) Include the tool(s) the reader will use to accomplish that goal.
Here are some examples:
- Accessibility Auditing with Axe for Automated Web UI Testing
- How to Deploy a Node Application and Database to Heroku
- Handling Static Forms, The Client-side Way
- Understanding Recursion in JavaScript
- Getting Started with Nodejs - An Overview and Walkthrough Tutorial
Introduction
This is the first section of your article that introduces your reader to your article and the goals they will accomplish after reading. This section ought to motivate the reader, summarize; what the article is about, why the reader should read, and what the reader will learn/ do in the article. Ensure to make this one to three paragraphs long.
Here is an example from my previous article (Image Optimization and Transformation with Cloudinary):
Prerequisites
In this section, you are to list out all the things your reader should do or have before reading your article as bullets or checklists. This is always useful to ensure your reader(s) can follow along without missing out at any section of the article. Please note that this should not be only practised with articles that entail some installation setup but any kind of article. It can just be as minimal as asking your reader(s) to grab cold water before reading the article. A great way to get them ready, yeah?
Here is an example from my previous article (Building a SlackBot with Node.js and SlackBots.js):
Headings
In this section, you are to break your article into parts and list them out as headings. This will allow you to write in a more organized manner and enable your reader(s) to read in an orderly manner. Ensure to make these headings an <h2> element
.
Here is an example from my previous article (Accessibility Auditing with Axe for automated Web UI testing):
- Introduction
- What is Auditing?
- Why Audit?
- Introduction to Axe Library
- Getting Started with Axe for Browsers
- Getting Started with Axe for Android
- Getting Started with Axe for CLI
- Getting Started with Axe for React.js
- Getting Started with Axe for Vue.js
- Bonus: Linting with eslint-plugin-jsx-a11y
- Conclusion
Conclusion
Here you should summarize your article just as similar to the introduction with a final closing note and maybe links for further research or study.
Here is an example from my previous article (How to Ask Effective Questions: A Practical Guide for Developers):
Attributions
Here ensure you add credits to resources, extracts, quotes, images or any other content of which you are not the creator.
Here is an example from my previous article (Getting Started with Hugo and Deploying to Netlify):