Writing Appreciation: A Container Explainer
Today’s Writing Appreciation Corner highlights a container explainer pitched at just the right level.
Writing Appreciation
Welcome to our Writing Appreciation series, where we highlight great pieces of technology writing around the web!
With these posts, we want to showcase "good" writing, explore what makes a piece of writing "good," and break down everyday "good" writing techniques for all of us.
Want to level up your writing skills? Check out our Writer Enablement workshops!
Containers defined for technical readers
This week’s piece of writing comes from the article, A primer on containers from the May 2021 edition of Increment Magazine. The section we’re looking at is in the second paragraph, right after the lede.
What impressed us? The definition is in the right place. The article’s author wants to talk about possibilities for a containerized future, and in order to do that, first needs to articulate what containers are. It’s a technology magazine, so readers are already in the space but may not necessarily be totally au fait with containers. This definition lays a clear, simple foundation, using appropriate language—pitched at just the right level for its technical audience.
“A container, in simple terms, is a bundle of everything an application needs in order to run, including libraries and dependencies. Unlike a virtual machine (VM), a container doesn’t include a full operating system kernel, relying instead on containerization platforms such as Docker, LXC, or rkt to get what it needs from the operating system layer. Containers can offer a range of benefits over VMs. For one, they generally use less memory and storage space when running applications. More broadly, they enable architecture that’s flexible and resilient, in which software runs consistently and scales smoothly.”
What makes this writing "good"?
Translating between complexity and value is a fundamental part of how we think and work at Open Strategy Partners. Effective strategic and product communication, in our view, is specific, clear, and approachable. Using the OSP Editing Codes, here’s what we think makes this paragraph so sweet:
TERM
TERM: “Define technical terms directly in the article to make sure your audience (at relevant levels of experience) are all on the same page with you.”
This piece defines the term “container” at the start of the article to make sure the readers have a shared understanding of what containers are before progressing to comment on the future of containers. This shows respect for the audience, bringing all readers along and not excluding anyone by assuming a level of knowledge.
CNECT
CNECT: “Use language that will connect with your target audience, but avoid jargon that will prevent non-experts from gaining value from your writing.”
Similar to TERM, but different, this code is about the words you use to explain something complex.
This passage is defining a technical term, and so context here is crucial. Increment is a magazine for a technical audience. The author uses careful word choice to pitch the definition at just the right level to connect with readers—coming in neither too high nor too low. Industry terms are included, like libraries, kernel, platform, and layer, but these words don’t prevent non-experts from gaining an understanding of what containers are. By choosing to come in at this level, the author establishes trustworthiness as a knowledgeable narrator, allowing less experienced readers to come along for the ride, and learn, looking up concepts if they need to.
SPOCK
SPOCK: “Use clear, logical thinking. Check that all evidence is directly connected with a cause/effect relationship to the claim.”
The definition has a clear, logical, narrative progression. It uses stepping stones of understanding to take the reader from point to point. It begins with what a container is. The use of the phrase “in simple terms” flags that the author is reducing the complexity. The writer then talks about what a container is not (by comparing it with a virtual machine). Finally, a fleshed-out description of the benefits of containers help the reader understand why they should care.
More OSP Editing Code Resources
- OSP editorial code Quick Start Guide
- Base documentation and full list of codes on GitHub
- Writing and editing are a big part of our podcast, too!
What to appreciate next?
Do you have an example of good, clear writing about technology that you’d like to share? Get in touch! Look ahead to more posts and, in the meantime, listen to our Communicate, Connect, Grow podcast to learn more about OSP’s editing codes.
Want to learn tools and techniques to consistently create authentic, compelling content? Check out our Writer Enablement workshops.
Follow along!
Follow us on Twitter — @open_strategy — and here on our blog.
Subscribe to our podcast, “Communicate, Connect, Grow,” via Apple Podcasts, Spotify, RSS Feed, YouTube, or wherever your ears listen!
Image Credits: Shipping container photo by Cameron Venti.