Introduction

In this issue, you will learn a considerably good way to begin your technical content. Left for me, there is no particularly perfect way to start a write-up, but considering a few factors, a set of must-do's present themselves.

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

Outline

• Introduction

• Outline

• Why Beginning Matters

• What Must be Included

  • Abstracts

  • Outlines

• Interesting the Reader

  • Explicit vs. Implicit Containment in the Body

• The Science of Titles

• Conclusion

Why Beginning Matters

How an article begins has a profound effect on whether it'll be read or not. This is why meta text or subtitle is important. By merely reading either of those, the reader can tell whether the article is relevant to them and their needs.

On this note, you have to write the beginnings even more carefully than you write 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 if necessary

• Write the first draft

• Review your draft

• 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 literally know what the end product of the article will be, and if you happen to leave the article halfway, it’s easier to know what to do when you eventually come back to finish it. Outlines also speed up the writing process, because once you have figured out the structure, all you have to do is to 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

In how-to guides and tutorials, a certain flow standard is expected, but the writer must keep the article developer friendly. The title of these articles already informs 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 decide between choosing tools X or Y for your development process. The article provides a thorough comparison of both tools from beginner friendliness to suitability for development tasks. At the end of the article, you will have a firm conclusion on which of these tools to use, as well as recommendations or best practices for using your chosen tool.

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

******Title: Get started 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 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 out for the engagements on your articles to judge whether they should accept your pitch.

Explicit vs. Implicit Containment in the Body

Learn to reduce the number 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 better understand explicit and implicit containment:

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, but if you are putting a lot of related ones in one article, it would be best to write a separate article about it and reference your article instead. 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 would rather you write a self-contained article that references your or other authors’ previous article on their platform. Some of them will greatly value your article if you embed a reasonable amount of self-contained links 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.

*You can proceed to write or embed an article that treats all of these here since they are related. If you are writing a new one, be sure to put the subsequent sentences that are skipped in mind.

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 be able to capture everything you did in the article, or maybe you just don’t know how to choose titles at all. 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, 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 simply reflect on the possible search statements using the keywords “compare,” “AWS,” “EKS,” and “ECS.” Since they are similar, your choice of the topic would be very close to either of those above.

Conclusion

I hope you learned a thing or two from this issue. If there are questions you would love to ask, please reach out to me via Twitter or Email. I am more than happy to respond to you about it. If there are topic ideas that you would like to read about but cannot find elsewhere, you can drop them as a comment below and I would do whatever I can about it.