Hello! This article is part of a Death by 1000 Cuts series that shines a light on glaring software development industry failures. I'm confident you'll return to 1000 articles someday.


Introduction

Both writers and programmers have difficulty setting context. Missing context plagues both prose and code. 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 into 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.

Always Be Closing

Content

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

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 teach the fundamentals. Solid and well-reasoned opinions on clean code and rock-solid architectures are essential.

Countless bugs haunt me. Petrified bugs in company backlogs have tormented me for over a decade. Inadequate content causes bugs as modules and architectures are built with murky documentation. Clarity is one of our most potent weapons against mediocrity.

Content is king, but context is the kingdom.

Context

I don’t apply one size fits all solutions. I provide adequate information within a given context. Many software design patterns exist, but every context dictates a different answer. I follow The Law of Instrument.

When writing prose, knowing your audience is critical. My to-the-point presentation landed well with my audience. After all, I was speaking to a team of software development professionals. However, not all are interested in architecture or diagrams, so a brief moment of context-setting would have added value.

A fort was built in the kingdom of context rather than a castle.

Acronyms

Why do people insist on using acronyms and find them cute?

Let’s take FY21, for example. It stands for the Fiscal Year 2021. The financial industry thinks confusion is part and parcel of their industry. Adding insult to that injury, companies pick any FY they please.

It’s easy to improve the context for a reader. Anyone can type the 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. Let’s increase context for our readers.

For Writers

  1. Spell out acronyms first.
  2. Only use acronyms when repeating them.
  3. Cite references and provide further context.
  4. Define your content in the first paragraph.
  5. Index longer content.
  6. Use headers.

For Programmers

  1. Create README.md files in your projects.
  2. First, summarize your document’s purpose.
  3. Link external documentation to expand the context.
  4. Provide diagrams.
  5. Create human-friendly tests.
  6. Assuming your reader knows less than you think.

I love programming and find joy in it. 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.

We can improve our context-setting game. There’s already a horrible signal-to-noise ratio on the Internet; let’s not add to it.


Other Deadly Cuts