Make it SIMPLE

Il semble que la perfection soit atteinte non quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retrancher.

…perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away…

ANTOINE DE SAINT EXUPERY, Terre des Hommes, 1939

As technical communicators, how do we ensure that our user instantly gets what the topic is about?

Here are the answers to that question, based on my reading of “Simple,” the central chapter of Chip and Dan Heath’s book, Made to Stick.

The good

Making something simple does not mean dumbing it down.

To make our content simple, we must:

  • Find the core idea and present it first.
  • Use the remaining content to support the core idea.
  • Eliminate everything else.

To illustrate this, Made to Stick describes a problem the US Army had a with orders: By the time commanders in the field received the order, it was outdated and the commanders had to choose between ignoring the order or implementing an order that no longer made sense.

To solve this problem, the US Army improved its communication protocols in 1980 by adding a commander’s intent (CI) to each order. The CI is “a crisp plain-talk statement, [to] the top of every order, specifying the plan’s goal, the desired end-state of an operation.” As a result, field commanders could act on the intention of the order, its core idea, despite changing circumstances in the field.

The CI sounds a lot like the DITA shortdesc element writers put at the beginning of their topic, just below the heading.

  • For a procedural topic, use the shortdesc to “explain what the task information helps users accomplish, the benefits of the task, or the purpose of the task.”
  • For a conceptual topic, use the shortdesc to, “introduce the concept and provide a concise answer to the question ‘What is this?’ and in some cases ‘Why do I care about this?’ If the concept is unfamiliar, you can start with a brief definition.”

I know some of you feel ill when you hear DITA mentioned in tech writing discussions. Even if you’re not using DITA, you can’t deny that it makes sense to give your readers a clear statement of the core idea at the beginning of your topic.

Doing this helps your reader to quickly “sniff” whether this is the information they are seeking so they can decide to read more or continue looking.

The bad

The opposite of identify the core idea and putting it at the top is:

  • Burying it somewhere else in the content.
  • Presenting multiple competing ideas.
  • Including tangential or irrelevant information.

We don’t do these things on purpose. They happen because we are either blind to them or lack the time and energy to revise them out of existence.

The ugly; revising to good

For me, words are like stepping stones that mark a path through a garden of information. When I revise a topic I’m working on, I reread the words and retrace the path I laid out earlier.

As I do this, I notice odd spots:

  • If I notice a misplaced stone, I move it to a better better spot or toss it out.
  • When I find a gap, I fill it with a stone from somewhere else or I generate a new stone by generating the idea that belongs there.

Usually, these changes create new odd spots in the path. So, with each move or fill, I spend a bit of time working it into place and reworking the surrounding material. I keep doing this, developing my thoughts and moving them around until I feel like I’m done.

Then I come back the next day and see a whole new set of things that are out of place. This is more of a problem with blog posts like this one than with technical content, whose structure is more defined.

The trouble with “eliminating everything else” is that I’m still generating new ideas (stones) when I’m revising. To solve this, I have to force myself to stop creating and focus only on removal. This isn’t easy if I’m attached to interesting by irrelevant ideas in the content. The solution is to save off a copy of the document before I start cutting away the excess. That way, when I finish the current topic, I can review the copy and use the interesting bits to generate new topics.

How to make your ideas stick. Part 1/7: Introduction

This is the first in a series of posts on my journey as a technical writer to improve how I deliver ideas to readers’ minds and make them stick there.

You never know where you’ll discover a gold nugget. I found Chip and Dan Heath’s work by chance in a Google docs slide template called Making Presentations that Stick.

Intrigued, I googled “Chip and Dan Heath” and found their New York Times bestseller, Made to Stick, why some ideas survive and others die.

This image shows a book cover, which reads, "New York Times Bestseller. Why some ideas survive and others die. MADE to STICK. Chip Heath & Dan Heath. With added material (now extra sticky)."

I was amazed to see that Amazon’s preview of Made to Stick generously gives away the “big secret” at the very heart of the book! It’s right there, free for anyone to read and use!

Most books keep their core ideas hidden away so you have to buy the book. Here, the authors flip that approach on its head. They give away the core idea for free, like open source software. They know these ideas are so simple and useful that they’ll find a much larger audience than if they were hidden. Then, that audience will turn right around, buy the book, and mention it to everyone they know. That’s what I’m doing right here.

The principles of the book boil down to an acronym, SUCCES:

  • Simplicity
  • Unexpectedness
  • Concreteness
  • Credibility
  • Emotions
  • Stories

I know, I know, you might be thinking – “ugh! Yet another business book with a catchy acronym!” But this book is SO much more than that. It’s a deeply researched and thoughtful work. Each principle is explained and demonstrated with a fascinating collection of stories – examples and anti-examples that give weight and depth to each principle. I’m amazed I didn’t hear of this book sooner. I wish I had read it years ago.

This book has had such a profound effect on me that I’m completely reworking the Explain Better talk I proposed to Write the Docs – Portland 2021 last month. I’ll hear back in a couple of weeks whether it was accepted. Even if it isn’t, I’ll hold an unconference on Explain Better.

In the following newsletters, I’ll discuss how I apply each of the SUCCES principles to technical writing.

Silicon Valley is dead! Long live Silicon Valley!


Remote work and the current health crisis has made Silicon Valley obsolete. Companies and workers are moving away in droves. Will they find a new place like Silicon Valley?

Yes and No. The end of the health crisis will enable a resumption of office work. However, having invested in and adopted remote work, organizations that embrace a hybrid remote+office business model will be more successful. New “Silicon Valleys” are forming at the optimal balance points of virtual and geographic communities.

Essay/personal notes

Note: This personal essay/post is definitely a work in progress (WIP). I am sharing this early version to get feedback and will continue making updates over time. Please feel free to comment and contribute your thoughts.

The future is already here; it’s just not evenly distributed.

Tim O’Reilly, founder and CEO of O’Reilly Media

I’m reading They Can’t Leave the Bay Area Fast Enough – As a tech era draws to an end, more workers and companies are packing up. What comes next? in the New York Times.

Great article. But I can’t get over the irony that so many of the interviewees are trying to recreate a Silicon Valley in Austin, Miami, Tallinn, or Topeka. Don’t you get it, with remote work, you will never find another place like Silicon Valley.

Wherever you point, there you are

In the Times’ article, John Gardner, founder and CEO of Kickoff, complains about the Bay Area:

But right now it’s just like: What else can God and the world and government come up with to make the [Bay Area] less livable?

John Gardner in “They Can’t Leave the Bay Area Fast Enough“, The New York Times, January 14, 2021

This was probably just one phrase out of a longer conversation with the journalist, Nellie Bowles, but it’s ironic that he points a blaming finger outward.

Entrepreneurs and tech workers like John and I absolutely flocked to the Bay Area to cash in on a mind-boggling inflow of venture capital, ballooning salaries, skyrocketing real-estate prices, and the occasional unicorn startup. We were the primary drivers of the nosebleed rents, million dollar bungalows, and soul-crushing commutes.

However, that stampede had a silver lining: We created the problems and started solving the problems we had created: We created the technology and culture that enabled remote work. By 2020, these innovations had become a metaphorical salt dome beneath the paradigm of work based on physical proximity.

As the corporations go…

Communications technologies transformed how and where businesses could operate.

“Exxon Will Move Its Headquarters to Texas,” James Barron, New York Times, October 27th, 1989

New technologies appear decades before they and replace old ones and change paradigms.

In the 1860‘s, transatlantic and transcontinental telegraph enabled organizations in urban centers, like large banks, to open branches in other major cities.

By the 1970‘s, multinational organizations were using telephone, teletype, and jet courier services to communicate with and operate far-flung branches in cities, towns, and hamlets around the world.

In 1976, Jack M. Niles et al. published The Telecommunications-Transportation Tradeoff, which envisioned telework and addressed questions such as “Are central business districts obsolete?”

Finally, the late 1980‘s saw an exodus of large corporations moving their headquarters out of high-priced central business districts. For example, following similar moves by Texaco, Mobil and J.C. Penney, Exxon closed its headquarters in The Rockefeller Center on 5th Avenue in Manhattan, and relocated it to Dallas Texas.

the Dallas area offered the best combination of factors from the standpoint of our employees’ personal and professional lives and from an overall business standpoint.

Exxon Chairman, Lawrence B. Rawl, “Exxon Will Move Its Headquarters to Texas,” James Barron, New York Times, October 27th, 1989).

Why North Texas? Because this move brought Exxon back to the heartland of America’s oil/energy industry: Oklahoma, Texas, and the Gulf Coast. Many of its employees were from these regions. Some of them found living in New York expensive and hard on their families. By returning, Exxon saved a bundle on real-estate and relocation expenses, and gained better access to a labor pool that had industry experience.

…so go the individuals

Similarly, the communications and computing revolutions had a transformative effect on individuals.

In the mid-to-late 1990’s, the first dot-com boom made Bay Area real estate prices explode. Many tech and office workers had moved to more affordable areas an hour or more from the offices where they worked. And they spent hours commuting daily back into those urban centers, where they worked at a computer. Many of us had a flashbulb moment: While installing 56k dial-up modems in our home computers or stuck in traffic during an expensive 2 hour bus ride to San Francisco we asked, “can I just work from my computer at home? And the answer was…“No. Not yet.”

Between 2000 to 2020, many elements came together to enable remote work:

  • Tech companies, faced with a skilled work shortage and competitive labor market, started offering remote work to attract, recruit, and retain tech workers.
  • Tech-savvy managers replaced traditional ones.
  • Software evolved to support remote work and was widely adopted.
  • High-speed always-on internet became the norm for many households.
  • Outsourcing to India other locales normalized distributed teams.
  • The cost of office space made scaling expensive.

But that wasn’t enough.

The salt dome collapses…

The current pandemic is the forcing function that has normalized remote work. Now many organizations have implemented remote work across the board. Employees have embraced it.

It would be an exaggeration to say “There’s no going back. The toothpaste is out of the tube. The worms are out of the can. (Who has ever opened a real can of worms?!) Most organizations still own the physical office space they had before the crisis. When we find a way to do it safely, if the vaccines are successful, we will be able to resume working in our offices.

I’m not an economist, but I’d guess that:

  • During economic growth cycles, it will be faster and cheaper hire remote workers and maybe close some offices.
  • During recessionary cycles, it will be faster and cheaper to close some office spaces and hire or retain remote workers.

So, what next?

  • There’s no need to live and work in Silicon Valley.
  • People and businesses are moving to more affordable locations.

And then what?

  • A fundamental change hiring patterns.
  • Downward pressure on salaries and wages, as companies gain access to a much larger talent pool.
  • A new “Lagrange point” where the costs and benefits of living in any particular locale balance out against the new semi-local and remote labor market.

These costs and benefits will include housing, quality of life, taxes, access to health care, the quality and speed of internet connections, business and personal taxes, and possible regional specializations based on legacy industries.

It is more important than ever to participate in virtual professional communities, hone your skills, and become indispensable and for your unique blend of skills.

Why I write about me instead of you

As a technical writer, I’m accustomed to telling users what to do using imperative phrases such as “do this or do that.” More recently, in my tech docs, I’ve adopted the practice of directly addressing the user by saying “you.” Many organizations have embraced this practice because it improves comprehension and establishes a warmer relationship with the user you, the reader.

In this personal blog, telling you what to do feels arrogant and high-handed. Instead, I want to move things further along that continuum of trust and familiarity. You know what’s best for you. If you find something meaningful in what I share, you’ll find a way to use it. If I still use imperative phrases, I do it out of habit and because that is how I tell myself to do things.

When I’m talking to you, I’ll say “you.” Nothing I say here is written in stone. I adapt and improve the ideas I discuss here to fit different needs and circumstances. It would be best if you did the same.

Overview: Write the Docs, Portland 2020

This year’s WTD conference was online/virtual only. This shift to virtual conferences make them more inclusive and accessible to attendees whose work, personal responsibilities, finances, or other constraints would normally discourage them from participating. Although this conference was well-attended by folks on the West Coast, by my estimate, half of the attendees were from other regions in the US and Canada; and a handful were from other parts of the globe. I enjoyed breaks and mealtimes with my family and sleeping in my own bed.

Day one, Sunday, August 9th was a pre-conference day with two sets of ten breakout sessions.

The writing day sessions were my favorite part of day one: We got to meet members of the doc teams from GitLab, Microsoft, and Mozilla and contribute to their open-source projects. It was interesting to see the similarities and differences in our tools and workflows.

The event hosting platform,, worked well. I stubbed my toe on a few potential improvements, but quickly adapted and had no trouble navigating the event site. The sessions were all live hosted on YouTube, which made it easy to pause the live feed, step away, and then return. I couple of times, after taking a quick break, I caught up with the live session by setting the playback speed to 1.25 or 1.5x. If you’re interested, WTD will probably published the recordings from this year’s event in a month or so. If you’re interested, you can also watch these recordings of last year’s conference.

Days two and three featured a series of fascinating speakers on the main stage.

There was also an unconference, where anyone could sign up for a “table” to give brief talks or discuss anything of interest. For example, shown below is the unconference schedule for the first half of day one.

These unconference tables were the best forums to discuss subjects of interest and meet fellow documentarians (the preferred term for everyone involved in this business). I got to meet more than a few of the main speakers to ask questions about their work.

I’ll probably write a few more posts about some of my favorite sessions. If you’re interested, here is a link to the complete three-day conference schedule.

Day of Learning

You didn't come this far to only come this far.

Today is Red Hat’s “Day of Learning.” We are encouraged to dedicate this day to learning.

  • This past year, I’ve been mentoring one of my peers. Earlier this week, I asked her to share her thoughts on what went well and what could be better. I got her notes this morning and spent some time reflecting on them and sharing my thoughts.
  • I listened several hours of The Servant: A Simple Story About the True Essence of Leadership, by James C. Hunter


One of the nice things about the Write the Docs – Portland conference two weeks ago, was it’s unconference.

An unconference is a participant-driven meeting. The term “unconference” has been applied, or self-applied, to a wide range of gatherings that try to avoid hierarchical aspects of a conventional conference, such as sponsored presentations and top-down organization.

This is exactly the right place to workshop new ideas with peers and stakeholders.