Hello, this article is part of my Death by 1000 Cuts series. I intend to shine a light on big software industry problems, and I have complete confidence I will have written 1000 articles someday.

Introduction

Missing context plagues both prose and code. Both writers and programmers have difficulty setting context. I’m guilty of cutting things short in the name of efficiency.

I recently presented Structurizr and PlantUML without specifying the context for my team and dove directly to the code & tools. I should have taken a moment to explain why clear diagrams are essential, but alas, I did not. I’ll do better next time.

In the following paragraphs I’ve laid out my view on Content & Context and will close with some solutions.

Content

We’re drowning in content. Content is EVERYWHERE, and most content invites you to empty your wallet. Wealth extraction is content’s most common purpose. Peddling ideas, proving a point, therapy, and education are other common use cases.

Why do I write content? I write content to learn through teaching. I love learning, and I love sharing. I have aspirations to be like Uncle Bob Martin and Martin Fowler. I love how these class acts have honed in on teaching fundamentals. Strong well reasoned opinions on clean code and rock-solid architectures are sorely needed.

I encounter countless software bugs every single day. Frequently it’s a bug that’s been in a company backlog for a decade. It pains me to be part of an industry that doesn’t commonly address the needs of its users. Poorly crafted content is the reason so many bugs exist. Clarity is a primary weapon against mediocrity.

For my part, I’ll do my best to create valuable content for all types of programmers without any distractions. I will never run intrusive ads alongside my content. I’ll edit pages with poor intros, and I’ll take responsibility for misleading content.

Context

I do not apply one size fits all solutions. I prefer to provide sufficient information and tools to craft a solution that works within a given context. Sure, there are patterns for many software designs, but every context dictates a different solution. After all, The Law of Instrument dictates more than a cursory glance at solution options.

When writing prose, knowing your audience is key. I find it annoying when people preach to me about things I already know. My to-the-point presentation may have landed well with my audience. After all, I was speaking to a team of software development professionals. However, not all of them are interested in architecture or diagrams, so a brief moment of context-setting may have added value.

Acronyms

Why do people insist on using isolated or overloaded acronyms and find it cute? It’s not, and it forces people to fish for meaning so an acronym can live.

Let’s take FY21, for example. It stands for Fiscal Year 2021. Adding insult to that injury, companies can pick any FY they please. The fiscal industry thought needless confusion was a fair price for investor convenience.

It’s not difficult to improve the context for a reader. Anyone can type Fiscal Year 2021 (FY21) at the top of their document, then refer to FY21 within their content: context set, and everyone’s happy including acronym fans.

Solutions

A little context goes a long way. Try the following approaches to improve the context for your readers.

For Writers

1. Spell out acronyms before using them in isolation.
2. Only use acronyms if repeating it throughout your document.
3. Cite your references and provide necessary context about them.
4. Clarify what you’re writing about in your opening paragraph.
5. Index longer content.
6. Use headers.

For Programmers

1. Create README.md files in the root projects an modules.
2. Summarize the purpose at the top of every document.
3. Liberally link to external documentation where applicable.
4. Provide diagrams; It doesn’t matter how you do it.
5. Create human friendly tests.
6. Don’t assume your reader knows everything you do.

I love programming, and I find joy in software development. But… the amount of lost context scattered on the Internet is astounding. There are so many code snippets on StackOverflow without library requirement context. Project README files with a title and nothing else. A solution to a problem without any context. I could go on, and on, and on, but I won’t.

I hope we all master craft our context-setting game. There’s already a horrible signal-to-noise ratio on the Internet; let’s not add to it.