Vale notes #2: Talk to experts and stakeholders

In addition to eating my own dogfood, I started finding and talking to experts and stakeholders.

For experts, I went to folks inside and outside Red Hat. At Red Hat, I talked to Fabrice Flore-Thebault and Yana Hontyk. Last year, they presented on using Vale with their documentation sets: Eclipse Che and CodeReady Workspaces. I talked to them about their workflow, the issues they had fixed, and results.

Outside Red Hat, I pulled together an unconference session at Write the Docs Portland conference with Mike Jang from GitLab and Jodie Putrino at NGINX. They spoke about their differing approaches to rolling it out at their organizations. Lynette Miles at TAG1 Consulting also contributed.

For stakeholders:

  • I talked with my manager, who was supportive.
  • I arranged a meeting for Yana and Fabrice to present their work to a small group of writers, content strategists, and managers who had expressed an interest in rolling out Vale. The group expressed a lot of interest, and we agreed there should be some follow-up actions, like additional pilot programs.

As an aside, Fabrice and Yana’s presentation included the following impressive graph. It shows how they iterated on both the documentation and Vale style rules to achieve nearly zero errors, both real errors and false positives, over the course of almost two years:

To prepare for the follow-up, I have created a repo that contains a preliminary set of Vale config files and styles: (definitely a work-in-progress).

Let Gmail to sort your email

Gmail does a pretty good job of categorizing your messages. You can train it to do better.

animation of user moving email to correct tab in gmail
Drag the conversation to the correct tab and click Yes. Google confirms that it will do this for you in the future.

Primary tab

Move messages that you must review, respond to, or take action upon to the Primary tab.

Social tab

  • Move social network notifications to the Social tab.
  • These messages duplicate information in your social networks.
  • You should be able to select and delete everything in this tab without missing it.
  • For example, notifications from Facebook, Instagram, YouTube, TikTok, WordPress, etc.

Promotions tab

  • Move business offers and informational newsletters to the Promotions tab.
  • These messages promote products, services, people, and ideas you like but can safely ignore.
  • You should be able to select and delete everything in this tab without missing it.
  • For example, messages from Medium, Substack, Seth Godin, Walgreens, and Pocket.

Updates tab

  • Move important messages that you should see but usually do not need to act upon to the Updates tab.
  • These include automated automated paystub/billing/account/renewal notifications.

Forums tab

  • Move messages from message boards and mailing lists to the Forums tab.
  • You should be able to individually review and delete most of these messages.

Routinely unsubscribe from notifications and newsletters you don’t read. Some senders let you cut the frequency from daily to weekly or monthly.

How to learned to love my email inbox

Stop using your email as a holding pen for I should do’s and somedays.

Me, thinking to myself 🙂

My email inbox was a bottomless pile of messages seen and considered but not resolved. Having so many small choices increased my stress and reduced my ability to get things done.

Then, about a month or so ago, I heard “inbox zero” mentioned. I intuitively grasped the concept and set about finding a better way to process my email that reduces my effort, stress, and mess. It’s most obvious feature is that you have zero emails in you inbox.

Now (Feb 20th) I’ve been doing this for over a month and have gotten faster and better at it. Here’s my updated system, which I call zero inbox.

Before you practice zero inbox, train Gmail to sort your messages.

  • Scan and delete the messages that don’t matter.
    • In Gmail, this includes everything in your Social and Promotions tabs.
  • Scan and read the messages that matter. Do the following and then archive these.
    • Respond briefly, if needed
    • Forward messages that require attention or action from others. Include a note saying what you want them to notice or do.
    • If writing this note takes more than a few minutes, schedule a 10-minute videoconference or call with them.
    • Make to-do tasks from messages require further action. (Don’t let yourself start working on this things now.)

When you’re done every message should be deleted or archive. Your inbox should be empty.

It helps to know what your focus/responsibilities/goals/interests are. Don’t waste time on messages that fall outside of these. Don’t get sucked into email threads that don’t concern you or your work.

Conquering my to-do list

Recently, I explained how I implemented zero inbox and started capturing tasks in todoist. By pushing all of my tasks to one place, I cut down on the burden context-switching.

However, this new approach has created a new problem: a ballooning to-do list. Now, I must find a better way manage these tasks.

Fortunately, this article in the Harvard Business Review reminded me of the classic Eisenhower/Covey matrix for prioritizing tasks.

More urgentLess Urgent
More importantDo it nowSchedule it soon
Less importantDivide & conquer, or delegateDelete it, say “No,” or toss
it in the “someday” folder
My adaptation of the task prioritization matrix from Eisenhower, Covey, and the HBR article.

I’ll let you know how it goes.

How I create my to-do list in todoist

Recently, I wrote about zero inbox, my hack for getting rid of email stress and mess. I also mentioned that it depends on having a to-do list that can link back to your email messages.

A few years ago, I started using the free version of Todoist, an elegant and dependable app developed by a Germany-based software company. I was so pleased that I upgraded a year or so ago to their Premium version for $3/mo, billed annually.

Getting the most out of my to-do list requires a little skill and effort. Here’s how I add tasks to todoist:

  • Using the todoist extension in Chrome, I create an item for (almost) every task I encounter. The extension makes it easy to link to an email message or browser tab that’s open.
  • I avoid creating duplicate to-do items for tech docs deliverables I’m already tracking in an enterprise tool, like Jira or Bugzilla. Duplicates double or triple the amount of maintenance work I have to do.
  • For tasks I’m already tracking in enterprise tools, I create an umbrella task like “Work on the top priority item in Jira.”
    • Because this work is my highest priority, I type “p1” as a keyword in the item’s description: Todoist highlights the task with a red checkbox and moves it to the top of my to-do list.
    • I also mention the “every weekday” keyword, so Todoist makes this item a recurring task.
    • Finally, I click “Add website as task” so Todoist includes a link to Jira in the to-do item. This helps me reduce the number of open tabs in my browser, so I’m more productive.

zero inbox

Recently, I started practicing zero inbox. I didn’t read any specific how-to articles or books, I just implemented it based on these two principles:


A quick search for “zero inbox” turned up this article and a 2007 Google TechTalks video on YouTube featuring Merlin Mann:

Inbox Zero – Merlin Mann – 2007

Merlin’s approach is a more nuanced (and probably more efficient) than mine. My approach is simpler:

  • I CHECK EMAIL between tasks and scheduled work periods.
  • I DELETE messages that have no informational value.
  • I ARCHIVE messages that seem to have some informational value. If the topic comes up in the future, I can search for it.
  • I DEAL WITH IT by replying to the message, adding a task to my to do list, and archiving the message. The to do task is linked to the archived email message.

This system works for me. It reduces my stress, mess, and effort.

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.