How to write good articles {#_how_to_write_good_articles}
Here are principles I keep in mind while writing an article:
Get to the point {#_get_to_the_point}
We're all busy people. Prove to the reader *quickly* that you know what you're talking about, and that your article is worth reading.
Your reader is here to read your article. Do not waste time convincing them to read it. Give them useful information promptly, and then start the tutorial.
In
this Lisp article
, my introduction is two sentences, and then I provide them with useful information ("Lisp's syntax and data share the same structure"). Then, the tutorial begins. The preamble is about 6 sentences, which I consider to be a maximum.
Speak casually and directly to the reader {#_speak_casually_and_directly_to_the_reader}
You are the author of an article. You have an identity and personality. Your reader is the reader, with an identity and personality. Your article should feel and sound like a conversation you'd have with a friend as you look over at their laptop screen at a café.
Use singular personal pronouns. When you speak of yourself, use *I*, *me*, *mine*. When you address or speak about the reader, speak directly to them with pronouns such as *you* and *your*.
This also helps avoid gender pronouns.
Wrong:
When a sysadmin boots his/her/their computer...
Right:
When you boot your computer...
Write in the present tense {#_write_in_the_present_tense}
You're speaking directly to your friend at a café, so everything in your article is happening *now*. Use the present tense as a subtle way to suggest to your reader that they're experiencing success as they read your article. Avoid future verbs like "will", future imperfect verbs like "will have been."
Wrong:
After you have run the code, you will see a penguin icon in the status box.
Right:
After running your code, a penguin icon appears in the status box.
When possible, avoid past perfect verbs like "have run" or "have executed" or "have installed."
Not ideal:
Once you've installed the application, you can launch it from the Activities screen.
Better:
After installing the application, launch it from the Activities screen.
Write with confidence {#_write_with_confidence}
If you don't believe in your article, then your reader won't believe in it either. Avoid words like "should" and phrases like "see if it works" and so on.
Wrong:
Now that we've written some code, let's see if it works!
Run the code.
You should see a penguin icon in the status box.
Right:
After running your code, a penguin icon appears in the status box.
It works!
It is better for your article to present a single, authorative solution than to attempt to be all solutions for every reader. Most problems do have different solutions. Should you have several answers to one question, consider writing several articles, each containing one solution.
Active voice {#_active_voice}
When a sentence has no clear object, it is considered "passive". Passive sentences diminish the cause and effect relationship, and so they tend to confuse readers. Always use the active voice.
Wrong:
The code is pushed to a repository from a terminal with the Git command `git push origin HEAD`.
Right:
Push your code to your Git repository by typing `git push origin HEAD` into your terminal.
Short and simple sentences {#_short_and_simple_sentences}
You can write sentences that are very complex. You can write sentences that are short and simple. You may be able to guess which is clearer from this very paragraph.
Simple sentences communicate effectively to readers regardless of their native language, age, reading comprehension, mental fatigue, or patience. Try to avoid complex sentences containing lots of commas and semicolons.
Wrong:
When the foo widget was invented, computers weren't commonly found sitting on the literal desktops of every user in an organization, but were instead large mainframes (accessed via dumb terminals), with several operators and a vast support staff, that took up an entire wing of a building.
Right:
The foo widget was invented when mainframes were common.
There was no such thing as a personal computer.
Instead, many users had access to a "dumb terminal", which had no computational power of its own, but interfaced with the organization's central mainframe.
Avoid jargon {#_avoid_jargon}
Avoid jargon. When you use specialized terminology, provide context.
Wrong:
Your system can benefit from hyper-jiggery, and you're likely to find that FRAPS doubles your system efficiency for half the cost of running FRIPS.
Right:
If you're a network engineer working on FRIPS (Fake Real Internet Protocol Singularity), then your system can benefit from hyper-jiggery (the process of converting FRIPS to FRAPS).
In the rare cases that your subject relies on jargon to convey its message efficiently, make it clear early on that your article is for readers with specific knowledge or experience.
You can do this blatantly:
This article assumes you're familiar with FRIPS and FRAPS.
If you're not familiar with FRIPS, then read my [Introduction to FRIPS] article.
You can learn more about FRAPS on their [Gitlab page].
Or you can do it subtly by speaking mostly to a knowledgeable reader, with "hints" to a inexperienced reader that this article may be beyond their experience level:
If you're a network engineer working on FRIPS (Fake Real Internet Protocol Singularity), then your system can benefit from hyper-jiggery (the process of converting FRIPS to FRAPS).
In this article, I demonstrate how to implement hyper-jiggery, and how to confirm a FRAPS install.
To learn more about FRIPS, read my [Introduction to FRIPS] article.
This article does not cover how to use FRAPS once you have it set up, so visit the project's [documentation] to learn more about that.
Avoid Latinisms {#_avoid_latinisms}
Latin phrases such as "e.g.", "i.e.", "ergo", "quid pro quo", "via", "etc.", and so on, are difficult to translate, difficult to understand for many readers, usually superfluous, and needlessly complicate sentences. Avoid them, replacing them with common English phrases: