You will learn a considerably good way to begin your technical content in this issue. Left free, there is no perfect way to start a write-up, but considering a few factors, a set of must-dosppresentstitself

This article will help you figure out how to start a new technical write-up. Keep an eye out for Freelance tips, which are helpful hints from experience that few people may not know about.

Why Beginning Matters

How an article begins profoundly affects whether it’ll be read. This is why meta text or subtitles are important. By merely reading either of those, the reader can tell whether the article is relevant to their needs.

On this note, you have to write the beginnings even more carefully than the other parts of the article.

When starting a new article, the procedure should be like this:

Get the idea or brief
Write the abstract (more about this below)
Write the outline
Do research
Rewrite the outline
Write the first draft
Review
Publish or submit

However, getting the first three steps right can greatly improve your speed, the usefulness of your write-up, and the reading experience.

Let’s see how in the next section.

What Must be Included

Abstracts

The Abstract is important, especially if you are:

Pitching a topic to a paid publishing platform
Writing content that you will not be finishing immediately.

The Abstract features:

The reason for the article
The intended audience
The learning outcomes
The flow of the article, in tandem with the outline

Outlines

The outline is an important but optional part of the technical article. It may be included in the published article, but its overall importance includes:

It aids in easy navigation and reader experience
It helps the writer keep track of progress during long-term writing
It provides structure to the piece
It makes updating/reviewing faster, just as using code blocks makes debugging faster

To write a perfect outline means to begin with the end in mind.

Freelance tips: It is very helpful to start your article by writing an abstract and an outline. You know what the end product of the article will be, and if you leave it halfway, it’s easier to know what to do when you eventually come back to finish it.

MUST READ: Get Better At Technical Writing (2024): Don't Start With Writing

Outlines also speed up the writing process because once you have figured out the structure, all you have to do is install the needed paragraphs in the subsections of the outline.

Interesting the Reader

There are different types of technical articles (not technical writing), including:

how-to guides
tutorials
blog posts
white papers
technical/research/benchmarking reports

A certain flow standard is expected in how-to guides and tutorials, but the writer must keep the article developer-friendly.

These articles’ titles already inform the reader what to expect in the content, like “How to implement the bubble sort algorithm in C++” or “Build a voting contract using Solidity.” In these cases, it is not necessary to interest or catch the readers’ attention — the title already tells them why the article is relevant to them.

In blog posts and reports, however, there has to be an introductory section in the beginning that tells the reader what to expect in the subsequent sections of the article.

This could be in the subtitle or introductory section. In case you are wondering about examples of blog posts, here is an example:

Title: Comparing Tool X and Tool Y

Introductory: This article will help you choose tool X or Y for your development process. The article thoroughly compares both tools, from beginner friendliness to suitability for development tasks. At the end of the article, you will have a firm conclusion on which tools to use and recommendations or best practices in using your choice tool.

Here’s another example with a more adventurous feel at the end:

Title: Get started with the Rust programming language

Introductory: In this article, you will gain a thorough overview of the Rust programming language, including its syntax, installation guide, best practices, and areas of application. You do not need any prior knowledge of Rust or programming to grasp the contents of this article, but you will make the most of the article by following through it practically. Rust is the most loved programming language by developers, and this article will show you why it’s so. Without further time wastage, let’s explore the crabby world of Rust!

Freelance tips: Some technical writing platforms look for engagements in your articles to determine whether to accept your pitch.

Explicit vs. Implicit Containment in the Body

Learn to reduce the amount of explicit references you make to outside sources to a reasonable extent. This is something I learned the hard way. A quick example will drive this through. Let’s scrutinize a paragraph to understand explicit and implicit containment better:

Solidity (embed link to Solidity website) smart contracts that run on the Ethereum (embed link to Ethereum website) blockchain can be developed with frameworks like Truffle (embed link to Truffle website), Hardhat (embed link to Hardhat website), and Foundry (embed link to Foundry website).
There are considerable differences between these frameworks; you can learn about choosing your best fit here (embed link to someone else’s blog post on the same blog platform).
Furthermore, this blog post (embed link to someone else’s blog post on a different blog platform) is a great guide to building smart contracts using the Truffle framework.
If you don’t know about smart contract development, you can read a previous article on Developing Solidity Smart Contracts the Right Way (embed a link to your previous article).

While this is a good paragraph, it has a lot of red flags. Official documentation and software websites are not bad. Still, if you put many related ones in one article, it would be best to write a separate article about it and reference your article instead.

MUST READ: Get Better At Technical Writing (2024): Don't Start With Writing

The same goes for nice articles written by other less-known authors; it is understandable to reference an article by Vitalik Buterin or Kelsey Hightower, but if the author isn’t renowned like these men, you are better off writing that article yourself and referencing it.

Keep in mind that if there is the possibility of one person in the world needing a write-up, then it is worth your time to write it.

Freelance tips: Paid publishing platforms prefer that you write a self-contained article referencing your or other authors’ previous articles on their platform.

Some will greatly value your article if you embed a reasonable amount of self-contained links rather than zero or explicit links to official software websites.

Rewrite:

Solidity smart contracts that run on the Ethereum blockchain can be developed with frameworks like Truffle, Hardhat, and Foundry. If any of this sounds alien to you, you should quickly read up this article* about smart contract development frameworks and examples of their usage.

*Since they are related, you can write or embed an article that treats all these here. If you are writing a new one, remember the subsequent skipped sentences.

The Science of Titles

Deciding on titles can be a headache sometimes. You want something different from someone else’s existing publication, or you don’t want something long but want to capture everything you did in the article, or maybe you don’t know how to choose titles. Whichever scenario you find yourself in, you are not alone.

Picking titles is a science; to pick the best title, you have to think like the reader and identify the keywords in the article. For example, imagine you wrote an article that helps developers choose between AWS EKS and AWS ECS.

MUST READ: Getting Better At Technical Writing (2024): The Beauty of Consistency

Your intending audience would likely be googling statements like the following to find your article:

how to choose between AWS EKS and ECS
compare AWS EKS and ECS
difference between AWS EKS and ECS
guide to choosing between AWS EKS and ECS

You can reflect on the possible search statements using the keywords “compare,” “AWS,” “EKS,” and “ECS.” Since they are similar, your choice of topic would be very close to either of those above.

Conclusion

I hope you learned a thing or two from this issue. If you have questions, please contact me via Twitter or email. I am more than happy to respond. If you have topic ideas that you would like to read about but cannot find elsewhere, you can comment below, and I will do whatever I can about them.