Footnotes and asides are a warning

This post is part of a writing advice series. Writing clearly is one of the most important — and overlooked — skills.

I’ve told a friend when editing a post that footnotes are a red flag and he shouldn’t have any. That’s excessive, but I do believe that they can be a sign that your writing isn’t as clear as it could be. The same goes for excessive use of commas, em dashes, and parentheses to set aside nonessential clauses or interject some additional meaning. None of these are bad on their own. They can add some color and personality to your writing. But if you find yourself using them frequently, you should stop and reconsider your phrasing.

Footnotes

Footnotes can be quite useful. When used in print or plain-text formats, they’re a good way to include links. In any form, they can provide additional context and reference that the reader might not care about. They have the option to go look if they choose, but it doesn’t interrupt the flow of the text.

But I often see footnotes used to present irrelevant information or to make a joke. While I appreciate a good joke, you have to consider if it’s appropriate to the context and the audience. When writing for an open source community, you should reasonably expect the audience to include a mix of cultures and languages. Will your reference make sense? If you have to go to great lengths to explain it, it’s probably not worth including.

Also ask yourself “is this footnote better as an inline link?” In a digital-first platform like a blog post or forum thread, you can make a key phrase a link to an explanation. This is great for the first use of jargon terms or when referring to previous work. In fact, if you find yourself including a lot of footnotes, maybe you should write an explanation post first that you can link back to in your main post. My recent post about decision logs is a good example. As I was writing an upcoming post, I realized that I included a reference to the concept of a decision log without explaining it.

Asides

When I talk about “asides” here, I mean phrases — like this one — in a sentence but set apart with some kind of punctuation. These sorts of asides are often non-essential. In other words, your reader doesn’t lose the meaning if you cut the the phrase.

These sorts of inline asides are bad for documentation where you’re trying to convey a set of steps. For other writing, they help keep the sentences from growing too monotonous. But overuse makes the train of thought hard to follow. Sometimes the answer is to drop the aside. Other times, you should break up the sentence. Try both options and see how they flow.

This post’s featured photo by Aaron Burden on Unsplash.

Ben formerly led open source messaging at Docker and was the Fedora Program Manager. He is the author of Program Management for Open Source Projects. Ben is an Open Organization Ambassador and frequent conference speaker. His personal website is Funnel Fiasco.

Share