Technical Writing 101: Ultimate Beginners Guide
Tags: writing, codenewbie, tutorial
Published: 2023-06-19 01:22:23

## Introduction

In today's world, there is a significant demand for technical information. As our society becomes increasingly reliant on scientific and technical products, we depend on technical writers to provide instructions on software usage, the creation of tangible items, and the execution of complex processes.
Similar to any endeavor in life, writing is a journey that requires time and practice to become comfortable with. Each new blog post provides an opportunity to acquire new knowledge and grow as a writer, gradually gaining strength in the process.
So it's likely that you have some or all of these questions if you're interested in delving into the field of technical writing:
- Why should one write?
- What does technical writing entail?
- How does technical writing distinguish itself from other writing forms?
- Which document types fall under the realm of technical writing?
- What are the structured procedures to be followed in technical writing?
- What are some of the tools commonly utilized in technical writing?
- How can one overcome imposter syndrome when embarking on their writing journey?

Before delving into answering these questions, let's first explore the fundamental question: What precisely is technical writing?

## What does the practice of technical writing involve?
Technical writing, also known as technical communication, extends beyond writing exclusively about specific technical subjects like computers. It encompasses any topic that involves specialized knowledge typically held by experts and specialists. An essential aspect of the definition of technical writing is considering the audience-the individuals who will receive the information. Technical communication involves effectively delivering technical information to readers, listeners, or viewers in a manner that is tailored to their specific needs, level of comprehension, and background.

## Why should you write?

- <u>To touch up</u>: Engaging in the act of writing compels us to revisit learned topics, conduct comprehensive research, and grasp underlying principles to explain them in our own words. Consequently, this process facilitates the memorization of thoughts and fosters a deeper understanding of necessary techniques or approaches.

- <u>To share our knowledge</u>: By sharing our knowledge, we enlighten the individuals who might have struggled with certain subject areas. Additionally, Sharing acts as a simple yet powerful means of connecting with others and nurturing a collective learning experience.

- <u>To affirm</u>: Affirmation plays a crucial role in our journey of learning and sharing. Through writing, sharing, and engaging with others, we connect with like-minded individuals who are open to collaboration and exchanging ideas. When our community supports or contributes to our work, it validates our efforts and eliminates doubts.

## Technical Writing Versus Academic Writing

-Technical writing and academic writing serve distinct purposes. Academic writing aims to present a specific perspective on a particular subject, showcasing research outcomes and displaying one's expertise. On the other hand, technical writing focuses on explaining and informing readers. 
-Technical documents often provide instructions on utilizing a product or service and may also describe manufacturer procedures for specific tasks. While both technical and academic writing may incorporate jargon, their fundamental goals and approaches differ significantly.
-Academic writing and technical writing cater to distinct audiences. Academic papers typically target fellow scholars within a specific field, although there are instances of academic writing intended for a broader audience. In contrast, technical writing is directed towards individuals who utilize the product or service in question.
-Those who specialize in technical writing possess a wealth of expertise gained through extensive experience in a particular field. It is important to note that, in academic writing, the depth of knowledge on a given subject may be relatively narrower compared to the expertise of the instructor who will be evaluating the paper.
-In technical writing, the inclusion of personal viewpoints is typically discouraged, whereas academic writing offers more flexibility in this regard. Students engaging in academic writing have the opportunity to incorporate their own perspectives and theories, allowing for greater freedom of expression. 
 

## Types of Technical Documents
Technical writing envelopes a diverse range of document types, which include:

1. <u>Technical Reports</u>: Are comprehensive documents that present findings, analysis, and recommendations based on research, experiments, or investigations.

2. <u>User Manuals/Guides</u>: Provide instructions and guidance on how to effectively use a product or service. They typically contain step-by-step procedures, troubleshooting tips, and safety precautions.

3. <u>Whitepapers</u>: Authoritative reports that delve into a specific topic, offering in-depth analysis, insights, and recommendations. 
Proposals: Documents used to present a detailed plan or solution for a project or initiative.

4. <u>Training Materials</u>: Provide instructional content, presentations, and exercises to facilitate the learning and development of specific skills, procedures, or technologies.

5. <u>Proposals:</u> Are documents used to present a detailed plan or solution for a project or initiative.

6. <u>Documentation for Software/IT</u>: This includes manuals, guides, and online help systems that explain how to install, configure, and use software or IT systems.

## The Writing Procedure

1. **Preparation**
When preparing to write, it is essential to:
-Establish your primary objective
-Select the appropriate medium for communication

2. **Audience Perception**
-Who is the intended audience for the written content?
-What is their level of familiarity or expertise in the subject matter?
-What are their expectations and preferences when it comes to receiving information?
-What are their potential concerns, challenges, or prior knowledge related to the topic?
-How can the content be presented in a way that fosters understanding, engagement, and trust among the audience?

3. **Research**
To effectively carry out research, focus on actively researching and comprehensively learning about the product you are writing for. Once you have gathered all the necessary information, your goal is to explain it to your target audience in the most coherent manner possible.
Research Methods:
<u>Primary research</u> involves collecting firsthand data through interviews, direct observations, surveys, experiments, questionnaires, and audio/video recordings. On the other hand, <u>secondary research </u>involves gathering information that has already been analyzed, assessed, evaluated, compiled, or organized into accessible forms. This includes sources such as books, reports, articles, websites, and more.

4. **Writing**
Once you have examined and organized all the information gathered during the research phase, the next step involves rephrasing the data in your own words and creating an initial draft. It's important to remember that perfection is not necessary at this stage. The draft serves as a foundation for your future documentation and can be refined and enhanced continuously until you achieve a complete and ideal document. Rather than striving for a flawless copy at this point, it is more beneficial to focus on maintaining flexibility. Allow your thoughts and writing to flow freely without worrying about word count or limitations. Simply continue writing as the words naturally come to mind.

5. **Revision**
The revising, editing, and proofreading stage of the technical writing process focuses on ensuring the coherence, presentability, and accuracy of your draft to meet the standards for publication. During this stage, it is important to:
-Revise, edit, and proofread your work to ensure grammatical correctness of expressions.
-Use appropriate punctuation, tone, and style formatting.
-Arrange paragraphs and sentences correctly, with each paragraph supporting a single idea.
-Eliminate redundant words, phrases, or information that may distract or confuse readers.
-Properly place visuals to enhance the understanding and presentation of the content.

Remember obtain feedback; it is advisable to consult with Subject Matter Experts (SMEs) in the relevant field you are writing about. This is because no technical writer possesses expertise in every technical detail, and seeking input from SMEs ensures accuracy and depth of knowledge in the content.

## Writing Tools 

1. <u>Grammarly</u>: Used to improve on grammar, spelling, and punctuation. It helps identify and correct errors, provides suggestions for clarity and conciseness, and ensures overall writing accuracy.

2. <u>Hemingway Editor</u>: Is utilized to improve the readability and clarity of technical writing. It highlights complex sentences, suggests simplifications, and identifies passive voice or adverb overuse, resulting in more concise and engaging content.

3. <u>LaTeX</u>: Used to create professional-looking documents with complex mathematical equations, formulas, and symbols. It is commonly employed in scientific and technical fields for its robust typesetting capabilities.

4. <u>Markdown</u>: Lightweight markup language used to create formatted documents that can be easily converted to HTML or other formats. It allows writers to focus on content creation while providing simple syntax for headings, lists, links, and formatting.

5. <u>MadCap Flare</u>: It helps in creating, managing, and publishing technical documentation in various formats, such as online help systems, PDFs, and mobile-friendly outputs.

6. <u>DITA (Darwin Information Typing Architecture)</u>: An XML-based standard used in technical writing to structure and organize content for reusability and consistency. It allows technical writers to create modular and topic-based documentation, making content management and localization more efficient.

7. <u>JIRA</u>: Project management tool widely used by technical writers to track and manage their writing projects. It helps in organizing tasks, assigning deadlines, collaborating with team members, and monitoring progress, ensuring efficient workflow and timely completion of writing projects.

## Overcoming Imposter Syndrome
Overcoming imposter syndrome when starting a technical writing journey requires a combination of self-reflection, mindset shifts, and proactive steps. Here are some strategies to help you:

a. <u>Recognize your achievements</u>: Reflect on your past accomplishments and acknowledge the skills and knowledge you possess. Remember that you have valuable insights and experiences to share.

b. <u>Embrace continuous learning</u>: Technical writing is a field that requires ongoing learning and growth. Embrace the fact that there is always more to learn and see it as an opportunity for personal and professional development.

c. <u>Seek support and feedback:</u> Surround yourself with a supportive network of peers, mentors, or writing communities. Engage in discussions, ask for feedback, and learn from others' experiences. Remember that everyone starts somewhere and that feedback can be constructive and helpful.

d. <u>Focus on progress, not perfection</u>: Shift your mindset from striving for perfection to valuing progress. Understand that it is normal to make mistakes or encounter challenges along the way. Each step forward is an opportunity to improve and refine your skills.

e. <u>Celebrate small wins</u>: Acknowledge and celebrate your accomplishments, no matter how small they may seem. Recognize the effort and dedication you put into your work and take pride in your achievements.

f. <u>Set realistic expectations</u>: Recognize that no one knows everything, and it's okay to ask questions or seek guidance when needed. Set realistic expectations for yourself and understand that growth takes time and effort

## Wrapping Up
-Create an online presence
-Networking works
-Branding matters
-Lay a brick everyday
"You learn to write by writing"