Tag: writing

Brad Frost’s “Just” article from a few years ago has struck a fresh nerve with folks. It’s a simple word that can slip out easily, that might be invoked to keep text casual-feeling, but the result can be damaging. Brad:

The amount of available knowledge in our field (or any field really) is growing larger, more complex, and more segmented all the time. That everyone has downloaded the same fundamental knowledge on any topic is becoming less and less probable. Because of this, we have to be careful not to make too many assumptions in our documentation, blog posts, tutorials, wikis, and communications.

Imagine yourself explaining a particular task to an earlier version of yourself. Once upon a time, you didn’t know what you know now. Provide context. The beauty of hypertext is that we’re able to quickly add much-needed context helpful for n00bs but easy enough for those already in-the-know to scan over. And making documentation more human-readable benefits everyone.

Ethan Marcotte takes this one step further:

I’ve noticed a rhetorical trope in our industry. It’s not, like, widespread, but I see it in enough blog entries and conference talks that I think it’s a pretty common pattern: namely, the author’s sharing some advice with the reader and, if the reader’s boss or stakeholders won’t support a given course of action, suggests the reader “just do the thing anyway.”

I think this is a bad, harmful trope. And I also think we should avoid using it.

“Just” is more insidious than the more overtly painful “Obviously” or “Simply”. In fact, there is a whole list of words that could go. The result of not using words like this? Cleaner sentences and more inclusive writing. Wanna make a difference? Be like Jeremy Keith and submit Pull Requests when you see the opportunity.

The best teachers I’ve had were ones that were cautious not to make me feel dumb.