Writer's Room: 5 tips for technical writing

As a technologist, showcasing your skill set is essential to gain attention from potential employers and like-minded developers, engineers, and technical professionals.

Whether you’re an Application Engineer,  Data Analyst, or UX Designer, by creating content, particularly technical tutorials and thought leadership articles, you can share your knowledge and center yourself as a thought leader for your specialist subject. From social media to creating your own blog page, there are many ways you can get your work seen!

At Andela, we have created the Writer’s Room – a series of blogs written by our technologists on a wide range of topics, from building a mental health chatbot to consuming SOAP – and we hold regular writing sessions to help our community hone their craft.

We’re sharing some of our exclusive tips to get your technical writing up to scratch, so you can start showcasing your talent!‍

Why write?

There are seven reasons why you should consider creating content – particularly blogging – as a technologist:

• Drive traffic to your website (if you have one)
• Increase your SEO
• Position yourself as a leader in your industry
• Attract potential employers
• Create content to boost social media presence
• Generate interest in your tech projects
• Build your ‘brand’ as a technologist

By creating a piece of content you’re putting your ideas and knowledge on display for all to see! The more you write, the more you hone your craft. And the better you get at writing, the bigger the audience you can attract.

Writing articles and tutorials entails:

• Conveying information
• Delivering news
• Providing a call to action
• Explaining or justifying an action/method

With a technical focus, you can create:

• A demonstration or tutorial
• Showcase an application use or project
• Detail specific instructions

Think clearly about what you want to share with your audience. Is it a broader thought leadership piece on teamwork and collaboration on an open-source project, or an in-depth tutorial on Android ML face detection with Camera X? Whatever it is that you want to say, it’s important to…‍

Know your audience

Before you get started you need to consider who exactly you’re writing for. Are you creating a beginner’s guide to Golang for a junior developer? Or sharing an intricate, detailed tutorial on a specific project you created using Python, for a senior-level reader? Whatever you’re looking to create, you need to keep your audience at the forefront of your mind.

Remember to speak to them peer to peer. You’re inviting your audience into your world, so ensure your tone is welcoming and friendly and that you use plain language. You don’t need to get out your thesaurus!

Grab your reader’s attention

Think about where your readers are when they find your article – where do you want them to end up? Do you want them to reach out to you, or to try the tutorial for themselves?  There are four key factors to keep in mind when speaking to your audience in a technical article:

• Give them a reason to care – what is so different about this tutorial or article? Why should the audience care enough to read? Ensure that in your introduction, you state the value and purpose of your article.
• Give them a reason to believe – help capture your audience’s imagination by giving them a reason to believe in your article. Explain why you’re the right person to write this blog, and that your knowledge is worthwhile and essential to the reader. Are you a specialist Python Developer? Then your Python Developer blog is essential reading! To keep an reader’s attention you need to ensure they believe in what you’re saying.
• Tell them what they need to know – offer clear and concise information detailing exactly what your reader needs to know. If its a tutorial, be precise with steps for the project and any code they might need. If your article is a broader, thought leadership piece, offer your audience quotes and statistics to back up your points.
• Tell them what they need to do – the best articles have a call to action. Do you want to encourage your audience to download and study a new programming language, or do you want them to follow you on social media and subscribe to your blog? Have a clear call to action at the end of your blog, whether its a link to your LinkedIn or a bank of resources.

Creating your article

As you’re drafting your article, consider the following points:

Title – Create a title that is going to capture your reader’s attention right off the bat. Make it accessible by terms like ‘tips, best practices, create, build’. Using numbers always helps, to set an expectation – just like this article is ‘5 tips’, considering using a specific number in your title, such as “15 steps to build a machine monitoring tool.” Also, including the word ‘you’ in your title will also get more viewer recognition. When you address your reader, it feels more personal and as if you are actually talking to them.

Structure – When starting your article,  remember don’t be too serious. Invite your audience to read and take part! Offer some motivation throughout, particularly if it is a tutorial. Terms such as ‘keep practicing, if it doesn’t work don’t worry, try again’ can help your audience stay focused and encouraged. Also, remember to write in the first person – write as you! – and address your audience directly, as if you’re having a conversation. ‘You can always use this app, I prefer to use…’ etc. are great ways of making your audience feel connected to you as a writer.  And don’t forget to be honest with your audience – tell them what went wrong for you, as well as what went right!

Images and videos – Blogs without images can look boring and lose a reader’s interest. A recent Google survey found that blogs with images have 94% more total views and attract reader’s attention instantly! When it comes to technical blog writing always use images of your work to illustrate your tutorial. Screenshot your step-by-step instructions and use inline code to make the tutorial clearer. You could also try using video links to make a technical tutorial clearer and easier to follow. If you decided to make a video of your tutorial, upload it to YouTube or Vimeo, and then embed the video into your blog.

‍

‍

Publish!

Have you chosen a platform for your technical writing? Perhaps you’re submitting your article to an online publication or blog, or you’re starting your own blog! Here are some suggestions for how to publish your work:

1. Andela.com – are you a member of the Andela Community? If so, you could write for us. Our blog is popular across the globe and ensures that our technologists stand out from the crowd. Check out our Writer’s Room program in our community slack – under the #Opportunities-Writing channel. You'll get paid for your published blog!‍
2. Medium.com – Medium is a great online platform for publishing articles and reaching audiences around the world. Medium’s audience tends to skew towards articles relating to technology, startups, and all business topics, so that makes it very compelling for software engineering blogs.‍
3. Start your own blog – Why not be your own publisher! If you have a website, consider starting a blog page. If you’re starting from scratch, create a blog on WordPress or Blogger, which you can then share far and wide on social media.

We hope our tips can help you get started on a path to becoming a technical writer.

Check out some recent blogs written by our own talented community for inspiration!

Building an AI-ready workforce

AI health innovation: Building a mental health chatbot using FastAPI, Langchain, and OpenAI in Python

The million-dollar challenge: 5 soft skills for virtual meeting success

‍

Want to be part of the Andela Community? Then join the Andela Talent Network!

With more than 150,000 technologists in our community, in over 135 countries, we’re committed to creating diverse remote engineering teams with the world’s top talent. And our network members enjoy being part of a talented community, through activities, benefits, collaboration, and virtual and in-person meetups.

All you need to do to join the Andela Talent Network is to follow our simple sign-up process.

Submit your details via our online application then…

1. Complete an English fluency test – 15 minutes.

2. Complete a technical assessment on your chosen skill (Python, Golang, etc.).

3. Meet with one of our Technical Screeners for a technical interview.

Visit the Andela Talent Network sign-up page to find out more.

If you found this blog useful, check out our other blog posts for more essential insights!