<h1>Quality Is the Most Important Metric</h1>
<p>Harper's Chrome extension continues to come along beautifully. I'm actively working to make it more useful and responsive, slowly crushing bugs that I hear about from our users and contributors. I will not go over them here, since our <a href="https://github.com/Automattic/harper/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aclosed">closed pull requests</a> should speak for themselves. I would, however, like to rapid-fire some of the small improvements and ideas about Quality that I've been brewing up this week.</p>
<img src="/images/guggenheim_2.png" alt="Living in a college town is strange. The whole place gets empty in the summer.">
<h2>Quality</h2>
<p>I first heard about big-Q Quality from <em>Zen and the Art of Motorcycle Maintenance</em> by Robert Persig. The book's length—whose main subject is the idea of Quality—speaks to its complexity as a topic. It's a great read, and I'd highly recommend it.</p>
<p>One important point the author makes is that Quality is inherently a human idea. It is hard, if not impossible, to define algorithmically or on paper. When one interacts with an object or a system, they come away with a sense of its Quality, without necessarily knowing exactly what led to that sense.</p>
<p>Some argue that in today's world of LLMs and fast-iterations, the real value of a good software engineer derives from their sense of Quality. We know whether a design decision or change to the code is worth exploring. We know how it will affect users. I don't think this argument is relevant to the LLM discussion at all, but I do agree with it in spirit.</p>
<h2>The Most Important UI Element</h2>
<p>Harper's Chrome extension has one critical UI element that user's should be interacting with more than any other: the suggestion box.</p>
<table>
<thead>
<tr>
<th align="left">Before</th>
<th align="right">After</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><img src="/images/before_suggestion_box.png" alt="Before the changes to the suggestion box"></td>
<td align="right"><img src="/images/after_suggestion_box.png" alt="After the changes to the suggestion box"></td>
</tr>
</tbody>
</table>
<p>When Harper locates a problem in a user's text, it underlines it and waits for them to notice. When they do, they have the option to click it and review Harper's suggestion. This is a flow typical of most spell and grammar-checking programs, so you're likely familiar with it. This process makes the contents and behavior of the suggestion box extremely important for user satisfaction.</p>
<p>After receiving some feedback related to the suggestion box's visual unpleasantness and difficulty to understand intuitively, I've started making some modifications. Nothing drastic—I don't want to confuse existing users. I've focused on making it more compact and use more visual storytelling. Now, when a spelling mistake should be corrected, it shows an icon rather than a full "Add to dictionary" label. I'm already getting positive feedback about the changes.</p>
<p>All-in, it seems like much of the design philosophy of the UI is being pushed further in the direction of Harper's core tenet: to get out of the way.</p>
<h1>Why Quality is Important</h1>
<img src="/images/chrome_web_store_front_page.png" alt="The Chrome Web Store Front Page">
<p>Quality is important for the Chrome extension (more so than other integrations) because of the Chrome Web Store's front page.</p>
<p>Extensions that get featured on the front page get a significant amount of free advertising. Millions of users view this page monthly. Getting on the page is guarantee of tens of thousands of new users, if not more.</p>
<p>Here's the rub: you can't get on the front page by paying for it or by chance. An extension is placed on the front page if and only if it meets a high bar of value and quality. In other words: you have to earn it. This is the essential reason why I've been working so hard on Quality these past few weeks: I'm trying to get on the front page.</p>
<p>Most of the steps I've taken in this direction are small enough to not be worth mentioning here. If you're curious, feel free to reach out!</p>

After receiving some feedback related to the suggestion box's visual unpleasantness and difficulty to understand intuitively, I've started making some modifications. Nothing drastic—I don't want to confuse existing users.

<p>After receiving some feedback related to the suggestion box's visual unpleasantness and difficulty to understand intuitively, I've started making some modifications. Nothing drastic—I don't want to confuse existing users.</p>

Quality Is the Most Important Metric

<h1>A Harper Record</h1>
<p>When we started work on <a href="https://writewithharper.com/docs/harperjs/introduction"><code>harper.js</code></a>, our goal was simple.
We wanted it to take less than 24 hours for a developer to embed high-quality grammar checking in their app.</p>
<p>A friend of mine, <a href="https://lukaswerner.com/">Lukas Werner</a> recently set a record for this.
In just over 15 minutes, he was able to embed Harper into Raycast, a command palate for MacOS.</p>
<p>This is fantastic news.
It's always great to see when your goals are having a real impact on someone's ability.</p>
<p>I hope you take the time to look at <a href="https://github.com/lukasmwerner/harper-raycast">the project on GitHub</a>.</p>
<p>In other news, we have some other small projects using Harper:</p>
<ul>
<li><a href="https://github.com/lockbook/lockbook">Lockbook</a></li>
<li><a href="https://stubby.io/">Stubby CMS</a></li>
</ul>

A Harper Record

<h1>Putting Harper in Your Browser</h1>
<p>When our users <a href="https://writewithharper.com">install Harper</a>, they should expect it to work anywhere they do.
Whether they're writing up a blog post in WordPress, leaving a comment on Facebook, or messaging a loved one on WhatsApp, Harper should be there.
Harper's core is extremely portable and it can run pretty much anywhere Rust can, so what's the big deal?</p>
<p>Why can't we just run Harper in the browser through a web extension?</p>
<h2>Running Locally</h2>
<p>There's a single complaint that I hear over and over again from people who use Grammarly or LanguageTool: they are both slow as molasses.
The process of writing has slowly evolved to be more complex than it needs to be.
With these tools, it writing looks like:</p>
<ol>
<li>Write a sentence.</li>
<li>Wait for the grammar checker to run (which takes as many as four seconds).</li>
<li>Fix the mistakes you made.</li>
<li>Go back to step one.</li>
</ol>
<p>The whole process reminds me of the <a href="https://thomasvogelaar.me/posts/the-copilot-pause/">copilot pause</a>.
This is part of why Harper is better than these other tools: it doesn't stop you from writing at the speed of thought.
Our most ardent users tell us this all the time: it feels great to <strong>just write</strong>, error free.</p>
<h4>How do we deliver grammar checking so quickly?</h4>
<p>Instead of hosting huge Java codebases in the cloud, we ship our software straight to the user's device.
Since there's no network request involved, we're able to put pixels on the screen faster than anyone else.
That's not to mention the privacy implications.</p>
<h4>Running Harper's engine locally in the browser presented some technical challenges.</h4>
<p>I'm quite proud that our JavaScript library can be installed as simply as <code>npm install harper.js</code>.
In order for that to work as well as it does, I needed to develop a system for:</p>
<ol>
<li>Compiling our engine to WebAssembly.</li>
<li>Shipping that engine to the browser.</li>
<li>Instantiating the WebAssembly code.</li>
<li>Build out the boilerplate necessary to make it feel native.</li>
</ol>
<p>Steps one and four were easy.
I just slapped <code>#[wasm_bindgen]</code> tags on a Rust library and put on a pot of coffee.
Steaming coffee is vital for writing tedious JavaScript.</p>
<p>Steps two and three, however, were a little more difficult.
The latest iteration of Google's extension standard, Manifest V3, places some heavy-handed rules on how executable code could be loaded.
I won't bore you with the details here.
Know that I spent many hours in JavaScript bundler hell.</p>
<h2>Running Everywhere</h2>
<p>Harper, nascent as it is, has the greatest market opportunity in the browser.
Over 3.5 <em>billion</em> people use Chrome on a weekly basis.
The plurality of knowledge workers spend most of their waking moments (as crushing as it sounds) in a web browser.
Half of the time spent at desks today is spent writing.</p>
<p>In order to address this market segment, we need a Chrome extension.
To lint text in the browser, I need a way to:</p>
<ol>
<li>Cleanly read text from input fields.</li>
<li>Locate the pixel coordinates of grammatical errors.</li>
<li>Render suggestions in popups.</li>
<li>Cleanly replace text in input fields when a suggestion is selected.</li>
</ol>
<img src="/images/harper_chrome_ext_2.png" alt="An example of Harper&#x27;s suggestion box.">
<h4>Reading and Writing Text is Hard</h4>
<p>The web may have standards, but there is nothing standard about it.
The "standard" way to input text is with a <code>&#x3C;textarea /></code> element.
Even so, most high-traffic sites implement their own text editors from scratch, using <code>&#x3C;div contenteditable="true" /></code> as a base.
Each of these cases required special care.</p>
<h3><code>&#x3C;textarea /></code></h3>
<p><code>&#x3C;textarea /></code>s are hard for one reason: it is difficult to get a good understanding of what they look like.
I can obtain their content with <code>input.value</code>, but I can't directly infer the pixel coordinates of grammatical errors inside them.</p>
<p>When the Harper Chrome Extension is offered an <code>&#x3C;input /></code> or <code>&#x3C;textarea /></code> element to analyze, here's what it does.</p>
<ol>
<li>Creates a new <code>&#x3C;div /></code>.</li>
<li>Copies all styles from the provided element onto the <code>&#x3C;div /></code>.</li>
<li>Using <code>position: absolute;</code>, it moves this <code>&#x3C;div /></code> directly on top of the provided element.</li>
<li>Copies the content of the provided element into the <code>&#x3C;div /></code>.</li>
<li>Uses the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Range">Range API</a> to turn the text indices emitted by Harper's engine into pixel coordinates on the <code>&#x3C;div /></code>.</li>
</ol>
<p>Using this mirroring strategy works, but has performance implications and additional complexity to handle scrolling within the element.</p>
<h3><code>&#x3C;div contenteditable="true" /></code></h3>
<p>Since elements in a <code>contenteditable</code> text editor (like Trix, Lexical, Gutenberg, etc.) actually exist in the DOM, I can just use the <code>Range API</code> to get pixel coordinates.
The trouble this time comes when I try to write a suggestion back into the editor.</p>
<p>Most documentation I could find suggests that you:</p>
<ol>
<li>Select the content of the element you wish to edit.
This can be done using <code>window.getSelection().addRange()</code>.</li>
<li>Call <code>document.execCommand('insertText', null, "YOUR TEXT")</code>.</li>
</ol>
<p>Much of this documentation acknowledges that <code>document.execCommand</code> is deprecated, but instructs you to use it anyway.</p>
<p>This is bad advice. <strong>Do not do this.</strong>
I spent an embarrassing amount of time trying to get it to work consistently.</p>
<p>The better way to replace text programmatically comes directly from the W3C standard:</p>
<ol>
<li>Manually edit the DOM in the fashion outlined by the suggestion chosen by the user.</li>
<li>Fire input events to instruct WYSIWYG editors to synchronize their internal state to the DOM.</li>
</ol>
<p>I'll admit that this is an oversimplification.
Much of the complexity here lays in determining which DOM nodes to edit or fire events on.</p>
<h2>Read the Source of Truth</h2>
<p>If you take one thing away from this post, it should be this: <strong>always read from the source of truth.</strong>
There is a lot of faulty information out there, especially when it comes to creating complex interactions with opaque systems.
If there is a source of truth, read it.
It may look intimidating or seem unnecessarily verbose.
It is that way for a reason.</p>

When our users install Harper, they should expect it to work anywhere they do.

<p>When our users install Harper, they should expect it to work anywhere they do.</p>

Putting Harper in your Browser

the_one_hard_thing

<h1>The One Hard Thing</h1>
<p>People (myself included) love to make cascading lists of tasks.
Actions, each of which are needed to improve a product, release a feature, or manage people.
These lists tend to explode in size, as more is asked of you.</p>
<p>There's one problem: I have only eight hours in a working day.
With so little time, how can I be expected to both maintain existing projects (bug fixes, etc.) while consistently delivering new functionality and maintaining a fast iterative loop?</p>
<h2>Insight</h2>
<p>I've had two key insights that have led to some tremendous personal productivity gains.</p>
<p><strong>First:</strong> I've observed that the difficulty of my tasks tends to follow a <a href="https://en.wikipedia.org/wiki/Pareto_distribution">Pareto distribution</a>.
A small number of tasks are shockingly difficult to solve, while a much larger set boil down to communication.</p>
<p><strong>Second:</strong> the morning is my most productive time of day.
For some reason, I'm able to tackle problems with an otherwise unusual mental clarity.
I suspect it's something to do with the natural human circadian rhythm or digestion.</p>
<h2>Leveraging the Pattern</h2>
<p>Motivated by these two observations, I've developed a habit: I dedicate each morning to its own <strong>difficult problem</strong>.
This is a single task that is chosen specifically to stretch my limits.
I call this my daily <strong><em>one hard thing</em></strong>.</p>
<p>Previous examples:</p>
<ul>
<li>Developing the first version of <a href="https://writewithharper.com/docs/integrations/language-server"><code>harper-ls</code></a> which is now used by thousands of developers daily.</li>
<li>Building the first 80% of the <a href="https://writewithharper.com/docs/integrations/obsidian">Harper Obsidian plugin</a>, which is also widely used.</li>
<li>Grokking how <a href="https://github.com/Automattic/jetpack"><code>Jetpack's Write Brief with AI</code></a> feature works (before I joined Automattic).</li>
<li>Compiling Harper to WebAssembly and embedding it somewhere no one has put a grammar checker before: <em>inside the web browser</em>.</li>
</ul>
<h2>Think About It</h2>
<p>I implore you: think about how you work.
How is your energy affected by the things you do in the day-to-day?
If you enjoy your eight hours, maybe the rest will be better too.</p>

Reach further each day. The minimum effective dose.

<p>Reach further each day. The minimum effective dose.</p>

Elijah Potter

The One Hard Thing

Insight

Leveraging the Pattern

Think About It

Other Stuff

Quality Is the Most Important Metric

A Harper Record

Putting Harper in your Browser