A Guide to Technical Writing

Author: @treciaks

Have you always wondered what technical writing is, how you can be one, what steps to take, or how to start? This blog post, inspired by the Twitter space we held with the same title, will cover all those questions.

What is Technical Writing?

Technical writing is the act of writing or a writing discipline that entails breaking down difficult ideas into much simpler chunks so that others can understand is excellent.

Although everyone may write, it's crucial for technical writers to make their writing easy to read and understand for their audience.

There are different types of technical writing it can be user guides, manuals, software manuals, it can be for educational material. The end goal of technical writing is to explain a complex topic to be easily understood or followed by people

What are the Benefits of Technical Writing?

There are so many benefits when it comes to technical writing and these are the benefits our guest speakers experienced:

• You get to learn, get paid and have a database of resources online. Such as your own articles. If you have a problem, your articles can be a lifesaver. With technical writing is you get to use your content as a reference in the future.
• You get can get a job, it expands your network and helps you learn concepts far more deeply and you can get paid for it as a side income. The more you write, the more it solidifies your knowledge of the topic you are writing about.
• It helps you to put yourself out there and builds up your personal branding.
• If you come from a self-taught background, you must have content that supports and shows recruiters that you know what you are talking about. That you are worthy of investing in.
• You’re increasing networking opportunities and you are helping the community.
• To write something is to learn twice. When you write about something, you do your research and learn stuff you didn’t know of. Also shows that you know how to adapt to the audience you are writing for.
• It is satisfying when someone uses your articles to improve their learning. # Technical Writing Process

The writing process is the series of actions taken by writers to produce a finished work and each of our guests has similar processes they follow, but each of them in their own way:

• Yuri
  Research, think of the audience if you don’t know what you are writing about, and organise the layout of the draft that you want to do, making it accessible to everyone.

• Bonnie
  Topic to write about, Brainstorming. Research, look to people who’ve written about the topic and read through the topics from other articles to understand the topic well. Print an outline, the skeleton of the article, and break them in a step-by-step way, it's easier when you have an outline. Send draft and wait for approval from the client, make readers know what the problem is and how it will benefit them if they read the article, editing. Make use of Grammarly and other tools, review and then it is good for publishing

• Kolade
  Even if I know what I am writing about, I still do research. The takeaway, research, check if my article is opinionated or not.

• Savvas
  Cater for the audience, simplify and use simple language for your audience.

• Emy
  Know who you are writing for, and have the goal to reach out to everyone. Like who is going to be reading your article, write the language you are going to understand. Tools like Grammarly and Hemingway help structure your sentences, but you have to know how as a writer to structure your idea without those tools.

• Graham
  Review style guides because each company has different style guides. Check abbreviations for first-time readers, they might not know the terminology, don’t assume. Codepen for code demos, do those before writing because it will guide what you can write about. Once you’ve finished writing everything, write the intro, because you want to optimise your intro to include keywords to help with SEO and write the conclusion in the end.

• Daniel
  What type of writing or method communicates the idea you want to put across? Is it a tutorial, is it a guide, maybe a deployment guide or a comparison or a persuasion article? How do you tell a story, is there a beginning and an end, and why it’s a problem? Think about all that as you are brainstorming for your article.

Discovering Your Niche

A simple definition of what a niche is is a specialized segment of the market for a particular kind of product or service. meaning, it is something that one or more people can identify you with because you are highly skilled at it. Now, is having a niche important for you as a technical writer? How do you discover your niche?

• Savvas
  Find something you are good at, it doesn’t have to be a tool or programming language, maybe your code, or anything. The more you are passionate about something, the more words will flow for your article, having a niche identifies you because it's something you are well versed in.

• Kolade
  If you want to write, don’t bother about the niche, As you progress in your learning, you will find something you are passionate about.

• Graham
  Write to newbies, write to seniors. Choose who you want to write for.

• Yuri
  How to find a niche, write about general things. You don’t have to force it, you will discover that you like to write about a specific thing and that will become your niche.

Simplicity vs Accuracy

• Explain things in your own words, don’t use difficult words. You can have technical content and make it more accessible to everyone.
• If a lot of things need base knowledge (the basics) and if you don’t know them as well. Refer them to other articles that explain what they don’t know.
• Be careful what you are leaving behind or including in your articles. Do not filter too much.
• Optimise for simplicity and accuracy, and break sentences into shorter paragraphs. The reason is when reading sentences, people stay and grab what you are passing across. Longer sentences are hard to digest.

Does the Length of Your Articles Matter?

• It's about the flow and less about the length. Storytelling comes in if you keep your reader engaged, with a nice story. If they are engaged, they will happily read through.
• It depends on what you are writing about, the subject and the context matter. Bear in mind, that the headings are nice and have an appropriate beginning because people scan through your article
• If you are writing about how to make a portfolio, make sure to explain things well and write a thousand words. The important thing to note, it is not the quantity but the quality of your articles that matters. The way you structure your article is also important. If the structure is good, the reader will receive your message well.
• When do you know when your article needs to be split into a series? Are the concepts you are writing about separate? If that’s the case, do split it. You want each article to answer a question or an end goal, context matter. If you think each item makes sense on its own then you can split it.

How to Promote Your Article

• Online platforms. Blog platforms because they have great SEO, it's okay to promote on your social media and make your friends share your work too.
• Optimise for SEO, make sure your article is well structured. Break in links where they are supposed to be linked. Organic traffic is free, share on LinkedIn, and Twitter, and share your articles to friends. If you can, implement email marketing to people

How to Start

You can start with Write For the Community programme we have here at Strapi.

Anyone with any level of experience with Strapi is more than welcome to start writing for us. You don’t have to be an experienced technical writer. What matters is that your knowledge will be more than enough to help the Strapi community or those interested in learning about Strapi.

Other than that, our guests also have shared what else you can do to begin your journey in technical writing:

• Graham
  Just write, after every article, review what to improve on. The introduction, the body, and what you could have written better. It's good to just start writing and you will see along the way. Start on dev.to because people are friendly. Don’t focus on the number of views on your article.

• Kolade
  Start with Hashnode, and then start writing for FreeCodeCamp because you get to work with editors who will edit your articles and who will help you with how you can improve. So you will get experience from experienced writers. When you have articles to present, you can apply to FreeCodeCamp

• Savvas
  Even tweets and Twitter threads, cutting articles into small chunks, is a nice way to start.

• Bonnie
  Check google dev docs on how to write your articles. Document your projects and write them in a way that if someone wants to build a similar project as yours, they can follow along and use it. Use dev.to and hashnode.com and other writing platforms. Writing is like building a CV because recruiters see what you are putting out there.

• Emy
  If you understand something well, write about it. If you continue to be consistent, people will notice and discover you and that is how opportunities come to you. One of the people who worked there can see your work and approach you for work. You can apply to write at LogRocket as well.

• Yuri
  Hashnode.com and medium.com helps you push your content forward. But most importantly, consistency.

Learn More About Technical Writing

There are so many great resources to learn about technical writing. Such as Emy’s article about “Starting Out With Technical Writing”, Yuri’s curated list of technical writing resources and Bonnie’s own book and resources to technical writing and Daniel’s GitHub repo which contains lists of paid technical resources.

With practice comes perfection. The only way to be a great technical writer is to write more. The more you write, the more you learn and get better. Once you are comfortable writing for the Write For the Community program at Strapi, you may also venture into contributing to making our documentation better.