Everything Technical Writing

Technical writing stands at the intersection of technology and effective communication. For people passionate about tech and writing, it offers an ideal career path. Technical writing is the skill of translating complex information into clear and understandable content. Whether it is a User document, Product document, or API documentation, technical writing empowers readers to not only understand but also to apply and appreciate the content.

In this article, we’ll explore the core elements of technical writing, from characteristics to types of technical content, to skills necessary to have, the tools that facilitate the process, amongst other things. Whether you are a beginner or an expert, this article promises to deepen your understanding of technical writing.

What is Technical Writing?

Simply put, Technical writing is a form of communication aimed at explaining complex technical concepts in a clear, structured, and concise manner. It is usually aimed at a specific audience.

Technical writing is a versatile skill and is employed across various industries. Some of them include Information Technology, Engineering, Architecture, Chemistry, Healthcare, Aeronautics, Robotics, Medical, Finance and Biotechnology.

Who is a Technical Writer?

A technical writer is someone who writes technical documents. The purpose of a technical writer is to convey knowledge in a straightforward and easy-to-understand manner to the intended audience.

Why is Technical Writing important?

The importance of technical writing extends across various industries, playing a vital role in effective communication and knowledge transfer. Here are some of them:

Technical writing simplifies complex information for easy understanding.
Technical writing helps experts to efficiently transfer specialized knowledge to a broader audience.
Clear documentation saves time by minimizing errors and boosting productivity.
User manuals, guides, and documentation created through technical writing make products and systems more accessible to users.

Characteristics of Technical Writing

Clarity: Technical writing should be written in a clear manner, making it easy for readers to understand the information being passed across.
Conciseness: It conveys information efficiently, avoiding unnecessary words, phrases, and unnecessary elaborations or details.
Thoroughness: It should provide all the necessary details the reader needs to accomplish their goals.
Audience analysis: Technical writers consider the background, knowledge level, and specific needs of the audience when crafting their documents.
Logical structure: Information is organized in a logical and structured manner, making it easy for readers to follow and locate relevant information.
Use of visual aids: Images, Diagrams, Graphs, Charts, and other visual elements are often incorporated to enhance understanding and retention of information.
Tone: Technical writing is typically formal and professional. It avoids slang and overly casual language.
Factual Accuracy: Technical writing must be factually correct. It should be thoroughly researched and verified to ensure precision.
Accessibility: Technical writing should be accessible to all readers, regardless of their level of technical expertise, individuals with disabilities, etc.
Relevance: Every piece of information should be useful and serve a purpose. Irrelevant details and information should be omitted.

Forms of Technical Writing

Technical writing encompasses different forms of writing, each tailored to specific communication needs and audiences. Some of them include:

API Documentation: API (Application Programming Interface) Documentation is a technical content geared towards Developers and provides Information on how to interact with the software’s API. Components of API Documentation are:
1. API Endpoints and Methods
2. API Authentication
3. API Request and Response sample
Product Documentation: This is a type of documentation that explains almost everything to know about a product or piece of software. There are 2 types of Product documentation:
1. System Product Documentation: They are for an engineering audience and are often used internally. It is more advanced as they are written for a technical audience.
2. User Product Documentation: They are written in simple and clear terms with very few technical terms. They are written for consumers who use their products. An example is the User guides/ manuals.
User guides/manuals: User Guides and User manuals are used interchangeably but they are slightly different. Simply put, User guides is a simple and more generic term while manual is a more specific and in-depth reference book. A User Guide is a broader term that encompasses any documentation or instructional material designed to help users understand and use a product or service. It can include various forms of documentation, such as manuals, tutorials, FAQs, and more.

A user manual, on the other hand, specifically refers to a detailed written document or booklet that provides comprehensive information about how to install, operate, maintain, and troubleshoot a product. It typically contains step-to-step instructions and technical details.
Technical Reports: these are formal documents that contain technical information or research findings about a specific topic. These reports are structured documents that present facts, data, analysis, and conclusions to inform a specific audience about a particular subject.
Release Notes: these are documents created for a particular product version and are immediately made available upon the release of the document. They detail the changes, updates, and new features in a product release. They are useful in keeping users updated about improvements and bug fixes.

A few others to note are how-to guides, SDK Documentation, White Papers, Test schedules, and Case Studies.

Skills Required for Technical Writing

Technical Writing requires a diverse set of skills to effectively communicate complex information in a clear and understandable manner. Here are some key skills required for Technical writing:

Writing skills: Strong writing skills are fundamental. A large component of a technical writer’s job involves writing documents. They use their writing skills to explain complex concepts in a clear and concise manner. Like every other tech field, you become a better technical writer by studying and practicing.
Ability to learn new things quickly.
Research skill: Ability to gather information from various sources including technical documents and online research.
Editing and Proofreading skills: Technical writers use this skill to proofread their documents and other writer’s work. They have a thorough understanding of grammar, spelling, and punctuation to help them identify errors.
Attention to detail: Technical writers use this skill to ensure accuracy and precision in all aspects of the document, including data, terminology, and formatting.
General Knowledge about software development and programming.

Technical Writing Processes

The Technical Writing Process is the several stages needed to create accurate and effective documentation. Here are the key steps in the technical writing process.

Define your audience and the purpose of the document: Knowing your audience is important for any type of writing. Technical writers should be aware that defining who their readers are is essential to their work. If you don’t know who you’re writing for, your document may become totally useless. Clarify the purpose of the document and identify your target audience. Understand their Knowledge level and specific needs. To understand your reader better, ask yourself the following questions before writing.
1. Who are my readers?
2. What do they need?
3. Where will they be reading?
4. When will they be reading?
5. Why will they be reading?
6. How will they be reading?

Asking yourself these questions helps you create a technical document that aligns with your reader's needs.

Write an Outline: The next stage is to write an outline. Write an outline that organizes the information structurally. Define sections, headings, subheadings and everything you feel should be included in the technical document.
Do your Research: The research stage involves gathering information about a product. You need to have a basic understanding of the product to be able to write about it. This is a really crucial stage as inaccurate or badly written documentation can seriously endanger the value of the service or product you are writing about.
Write your first draft: The next step after gathering the necessary information is to write your first draft. Don’t worry about making it perfect. Focus on clarity, conciseness, and accuracy.
Rewrite the first draft: Take some hours or days off after writing the first draft. Rewrite the first draft and focus on making sure it is accurate, complete, and easy to understand.
Fine-tune and Polish: Conduct a thorough review of the document to catch any remaining errors and inconsistencies. Identify and correct any typos, errors, or minor mistakes.
Ask for feedback: Before publishing, if possible ask for feedback from friends, mentors, or just anybody, so as to identify some errors missed out or suggest ways to improve the documentation.
Publish and Share: The last stage is to publish the documentation on any site of your choice. After which you can share on all social media platforms to reach more audience and encourage more engagements.

Tools for Technical Writing

There are various tools available to assist technical writers in creating effective documentation. The choice of tools often depends on the specific needs of the writer. Here is a list of commonly used tools for technical writing

Research tools: Research skills are a must-have for every technical writer, it is crucial for writing correct and concise articles. Some of the tools to aid better research are :
1. Google
2. Books and articles
3. Libraries (both online and offline)
4. Quora
5. Stack Overflow
Note-taking tools: When conducting research, there are various materials you might need to come back to. Having a place to store them for easy access is essential. Some of these tools include:
1. Traditional Note apps on phones and system
2. Google Docs
3. Google Keep
4. Notion
5. Evernote
Writing tools: These are the tools used for writing. Some of these tools include:
1. Google Docs
2. Google Keep
3. Dropbox paper
4. Microsoft Docs
5. Vscode ( write in markdowns)
6. SimpleMDE ( write in markdowns)
Media/ Visual tools: These tools are used for creating and editing images, screenshots, videos, and screencasts. They are also used to create cover art, banners, diagrams, charts, etc. Some of these tools include:
1. Canva ( media creation tool)
2. Unsplash ( free images)
3. Giphy.com ( gifs)
4. Draw.io ( create diagrams and charts)
5. Carbon ( code screenshot tools)
6. Camtasia ( screencast )
7. Fireshot ( screenshot webpages in browser)
Editing tools: These are used to check for errors, edit articles, rephrase sentences, check your grammar, and check for plagiarism. Some of them include:
Publishing tools: There are a lot of platforms to publish your technical articles. Some of them include:
1. Hashnode
2. Medium
3. HackerNoon
4. Dev.to
5. GitHub Readme

Note: You can also decide to publish the article on your personal or client blog.

Collaboration tools: Collaboration is a crucial aspect of technical writing, especially when working with diverse teams or contributors. Here are some collaboration tools that can enhance the efficiency and effectiveness of technical writers :
1. Google Drive
2. GitHub
3. Notion
4. Trello
5. Airtable
6. Asana

Best Practices in Technical Writing

Know your audience
Spend a lot of time planning
Use good, correct, and clear English
Avoid over-explaining.
Avoid the use of technical jargon and buzzwords
Use active voice
Don't use fancy words
Use appropriate visuals to clarify concepts
Research well
Use a consistent format, be consistent in your writing
Test your documents by asking for feedback and reviews.
Keep your technical documents up to date.

Writing in Markdowns

According to Wikipedia, Markdown is a lightweight markup language for creating formatted text using plain text editors. They are a simple and efficient language used by Technical writers to create clear and concise documents that are easy to read and understand.

Markdown is widely used for formatting and styling content on the web, especially in scenarios where a simpler alternative to HTML is preferred. Check this article for a better understanding of Markdown and how they are used in Technical Writing.

SEO in Technical Writing

Search engine optimization (SEO) is the process of optimizing a website or web page to rank higher in search engine result pages. The goal is to increase the quantity and quality of organic traffic to a website by improving its visibility and relevance to search engine users.

Importance of SEO to Technical Writer :

It increases the visibility of Technical documents
It helps your Technical document rank higher on search engines
It helps the technical documents reach their intended audience
It helps technical writers to freely compete with other competitors.
SEO tools and analytics provide valuable insights into user behavior
SEO tools and analytics help in Audience analysis

How to optimize Technical Contents:

Use relevant Keywords and Phrases
Include Keywords in your headings and subheadings
Utilize Header tags properly
Add Internal and external links
Write descriptive and compelling titles
Create meaningful meta-description
Add Alt texts to images
Embed Media
Write compelling Calls to Action (CTA)
Regularly update and maintain contents
Use Seo tools

Building your Technical Writing Portfolio

A well-crafted portfolio is essential for showcasing your skills and landing freelance gigs or job opportunities in technical writing. A few things to take note when building your portfolio are:

Select your best works only.
Include diverse samples of your work ranging from User guides to white papers, API documentation, etc.
Include original content, avoid plagiarism.
Include collaborative projects.
Use a professional format.

Freelancing in Technical Writing

Freelancing is a good way for Technical writers to generate income before or while working as a full-time technical writer in a company. There are several ways to generate income as a freelance Technical Writer. Here are 2:

Method1: Guest Writing

Guest writing is when a writer writes technical content for blogs. This is the most common way for Technical writers to generate income, improve their skills, and gain exposure. There are a lot of blogs to write for, some of them include

Method2: Using Freelance Job Platforms

Another to generate income as a freelance technical writer is to find jobs on freelance job platforms like Upwork, Fiverr, and Freelancer. Set up a good profile that showcases your skills, experience, and bid for projects posted by clients.

Technical Writing Courses

There are numerous online courses and resources available to individuals looking to enhance their technical writing skills. Whether you are a beginner or an expert, these courses cover various aspects of technical writing.

Courses :

Google Technical Writing Course (Free)
Udemy Technical Writing Course (Paid)
Tech Write and Earn (Free for 7 days and Paid for life)

Technical Writing Communities

Alone we can do little, together, we can do so much - Helen Keller

Engaging with technical writing communities is a great way to stay updated on industry trends, exchange ideas, and seek advice from fellow professionals. Here are some popular technical writing communities where you can connect with other writers, share experiences, and learn from each other:

Write the Docs: Write the Docs is a global community focused on documentation, including technical writing. Write the Docs Nigeria Twitter (X) page, Write the Docs Kenya Twitter (X) page
Non-Tech in Tech: They are a community of Non-techies in Africa.
Technical Writing Community on LinkedIn
Technical Writer Forum on LinkedIn

Conclusion

Technical writing just like every other field in tech involves constant learning. You get better by reading, learning, and writing more articles.

Read, read, read. Read everything - trash, classics, good and bad and see how they do it. Just like a carpenter who works as an apprentice and studies the master. Read! You’ll absorb it. Then write - William Faulkner

Create a personal blog, write, share your work, ask for reviews, and improve your documentation.