Technical Writing; What And How?
(Slack Chat Discussion) with Edidiong Asikpo a.k.a Didicodes
She Code Africa: Kindly introduce yourself , what you do and fun facts about you?
Didicodes: Thank you for having me SCA. My name is Edidiong Asikpo but you call me Didicodes or The Drip. I currently work as a Software Engineer at Interswitch Group. I am passionate about technical writing, contributing to open source organizations, and building developer communities. Fun facts: I can spend an entire week or month watching movies if I could. I really love listening to Trap music.
She Code Africa: It’s true some designers and developers are still confused about what technical writing is. Please can you explain technical writing briefly?
Didicodes: Technical writing has been defined differently by various authors and writers but I found the definition by Grammar very interesting. According to Grammar, “Technical writing is a type of writing where the author is writing about a particular subject that requires direction, instruction, or explanation.
It is an efficient and clear way of explaining something and how it works.” To me, technical writing is about organizing the most important facts and explaining complex problems in a very efficient way that’s easy to understand by the audience.
She Code Africa: How can one become a technical writer? How can the skill be acquired?
Didicodes: A common assumption among many would-be writers is the thought of not being able to write because they were not born with the gift or skill of writing. Which raises the question: Are writers born or made?
I was curious to know what other people thought about this popular myth so I made a tweet about it. I was amazed at the fact that some people thought writers were born, others thought writers were made and another set of people thought writers were both born and made as well.
I personally believe that anybody, whether born with the skill or not, can learn how to become a great writer. I wasn’t born with the gift of writing, but I decided to be intentional about learning how to write and the rest is history.
The technical writers you see today had to develop or learn certain skills to become good at writing.
Here are 5 important skills needed to be a successful technical writer:
- Writing: The first and most important skill every technical writer needs is writing. I know it might be confusing to see that writing is one of the skills required to be a technical writer because you probably think technical writing and writing are the same thing but they are not.
Writing is the process of using symbols (letters of the alphabet, punctuation, and spaces) to communicate thoughts and ideas in a readable form while Technical writing is the process of communicating or conveying one’s ideas, views, instructions, and suggestions more logically and technically.
Therefore, you must first understand how to write before going ahead to explain that topic or concept clearly and technically.
2. Audience Perception: Another important skill technical writers need is the ability to identify their target audience. To know who’s your target audience, ask yourself the following questions before you start writing:
- Who are they?
- What do they need?
- Where will they be reading?
- When will they be reading?
- Why will they be reading?
- How will they be reading?
When you get the answers to the aforementioned questions, it will help you tailor your writing to that audience which will in turn help you pass the message effectively.
3. Technical Skill: The goal of a technical writer is to enable readers to understand a highly complex process or concept clearly. For this to be achieved, technical writers need to be well familiarized with the topic they are about to write on.
“If you can’t explain it to a six year old, you don’t understand it yourself.” ― Albert Einstein
The quote above by Albert Einstein echoes the need to understand the technicalities of something before explaining it to someone else.
4. Research: The importance of understanding how to carry research as a technical writer cannot be over emphasized because researching on the topic will equip you with a broad understanding of the subject. This broad understanding will ensure that your text is accurate and communicates the necessary data most efficiently. Simply put, Google the hell out of things.
5. A Unique Voice — We are all unique and that is why it is important to sit alone with your thoughts and let your mind flow freely as a writer instead of copying other authors’ content.
“It ain’t whatcha write, it’s the way atcha write it.” —Jack Kerouac, WD
This is extremely important because people learn in different ways & your content (voice) might be what someone out there is hoping to read before they finally understand that concept.
She Code Africa: So What are the purposes of technical writing?
Didicodes: The purposes of technical writing are enormous. As a technical writer, you:
- Reinforce your knowledge
• Help others
• Grow your writing skills
• Build your portfolio
• Make money
She Code Africa: In what ways can technical writing help one learn?
Didicodes: Technical writing, though primarily concerned with sharing technical knowledge and experience to help others, also helps to reinforce your knowledge on the topic you’re writing about while still demonstrating your technical ability and level of talent.
Technical writers have the great benefit of becoming lifelong learners because they need to be well-versed in that field they are writing about in order to communicate the content clearly to readers.
She Code Africa: How can one get started in technical writing without any background experience?
Didicodes:
- Take a Course On Technical Writing
- Read books and articles
- Write More
- Stay Consistent
Take a Course On Technical Writing
Technical writing is an in-demand skill and employers want to hire the best writer on their team. Taking a course on technical writing is highly underrated but it is very important because you will discover diverse tips that will help you become a better writer. My technical writing skills significantly improved after I took a Technical Writing course by Google and I highly recommend you take the course as well.
Read books and articles
“Read a thousand books, and your words will flow like a river.”― Lisa See
Reading is very essential because it will help to enrich your vocabulary, keep you abreast of current trends, discover what’s going on in the writing world, and also helps keep the spirit to write alive.
Write More
“You learn to write by writing, and by reading and thinking about how writers have created their characters and invented their stories. If you are not a reader, don’t even think about being a writer.” ― Jean M. Auel
Even when you take all the technical writing courses and reading all the books in the world, that doesn’t make you a writer. The only time you can and will be classified as a writer is when you write. So you need to let your thoughts flow freely while you put them down.
Stay Consistent
“You don’t start out writing good stuff. You start out writing crap and thinking it’s good stuff, and then gradually you get better at it. That’s why I say one of the most valuable traits is persistence.” ― Octavia E. Butler
Just like every other skill, you get better at writing when you keep writing consistently. Aim to write at least one article every month and you will be shocked at the way your writing skills will improve if you keep doing it consistently.
She Code Africa: What are the Technical writing Tips every witter needs to know
Didicodes: Yes! Here are some things technical writers need to take note of before and after they’ve completed the first draft of the topic they decide to write about.
- Learn to follow a style guide when writing. It helps you stay on track and follow the best writing principles.
- Make your paragraphs support a single idea. Don’t cram everything within one paragraph.
- Write short, clear, and precise sentences because simplicity is the ultimate sophistication.
- After writing your first draft, read your content out loud while assuming you are the reader. This will help you spot words that can be rephrased.
- Edit your first draft only when you are focused.
- Seek feedback by consulting with experts in the field you are writing about because no technical writer knows every technical detail.
She Code Africa: What would you consider the most important step in the writing process?
Didicodes: To me, the most important step is starting. If you don’t start you might end up not writing again. I believe every other important thing comes after you’ve started writing because if you think about it, you can’t edit or improve an empty file or paper.
She Code Africa: What are the tips or experiences one needs to have before participating in Google season of Docs?
Didicodes: According to Google, you must be at least 18 years old at the time of registration. You must also have prior experience as a technical writer and be eligible to work in your country of residence. If you meet these qualifications, then you can apply to participate in the Google Season of Docs program. I wrote an article about the entire process, the benefits of participating and tips to help anyone who is interested in applying for the program. You can read the article here:
She Code Africa: Are there other programs ladies interested in technical writing can participate other than Google Season of Docs?
Didicodes: According to Glassdoor, technical writers make between 50,000$ to 100,000$ annually. Most communities pay writers between 100$ to 500$ per article published on their platform. You can find some of those paid community writing programs here https://github.com/malgamves/CommunityWriterPrograms.
She Code Africa: What are the resources one can learn more about technical writing?
Didicodes: Here are some resources I recommend
- A curated list of awesome resources: articles, books, videos, tools, podcasts about technical writing
• Google’s Technical Writing Course
• Free Technical Writing Courses — Technical Writing is Easy
• Top 7 Online Courses in Technical Writing — Kesi Parker.
She Code Africa: There are times when I decide to write an article on a topic but then midway, I lose steam. The topic doesn’t spark joy anymore. Has that happened to you and how do you handle it?
Didicodes: It is good to know you found the session enlightening. Thank you! To answer your question, I don’t think I have experienced something similar to this. In my case, I think it is not really necessary to write about the topic anymore because there is already a lot of content about this same topic in the world. Whenever this happens, I am always on the verge of not publishing the article anymore, but I realized we don’t write to educate people, we write to get better at writing, improving our knowledge about the skill we are learning and also store up information for our future self just in case we want to forget something about the topic.
I recently published an article titled Getting started with the DOM, if you are a web developer, chances are that you’ve probably heard about the DOM and I almost didn’t publish this article because there are already a number of contents about this same thing. When I summoned the courage to publish, the article blew up on Twitter and so many were talking about how they never understand what the DOM was about or how to manipulate it with JavaScript. Then it dawned on me that people learn in different ways & your content might be what someone needed to read before they finally understand that thing. So even if you don’t have the spark anymore, go ahead to write and publish the article because someone somewhere will find it useful.
She Code Africa: We definitely would look into writing after now.
Generally, how long should a good tech write-up be? Is there anything as too lengthy? What platform/place would you recommend sharing for those who don’t have personal blogs/websites?
Didicodes: There is no specific length or number of words that are used to define if a tech write up is good or not. As long as you pass the message intended then it is good to know. However, always remember that simplicity is the ultimate sophistication so it is important to write short, clear, and precise sentences.
For platforms, I totally recommend using Hashnode’s Devblog here https://hashnode.com/devblog to create your own blog and publish your articles. Hashnode has a Developer Community as well so your articles will also gain a lot of traction as well.
She Code Africa: Edidiong thank you for sharing your tips on technical writing. Can you tell us how we can overcome writer’s block ?
Didicodes: Writers’ block is definitely a thing. To overcome this, I suggest you take a break for a couple of hours or days and then start writing again after you are well-rested. I also recommend that you try sitting alone with your thoughts and let your mind flow freely. It’s amazing what you can come up with. The most important thing is to finish that first draft and every other improvement will happen after.
We hope you found this article interesting, do follow us on our social platforms; Facebook, Twitter, Instagram, Linkedin . You can also join us on our Slack Community to engage in more interesting chats like this.
