In April 2015, Apple introduced the new MacBook, a small, lightweight machine with a new keyboard design. The keyboard used what Apple calls a “butterfly mechanism” to allow for a thinner design while ostensibly still offering a satisfying typing experience. In general, response to the new keyboard was tepid. The issue was key travel—or lack thereof. In their not-exactly-glowing review, Ars Technica said, “Some will hate it, but we suspect most will be fine with it.”
In late 2016, Apple updated its MacBook Pro lineup to use a new, second-generation butterfly mechanism. This switch added some much-needed key travel and quelled the brouhaha over the usability of the original design.
Unfortunately, by early 2018, enough anecdotal evidence had accumulated to confirm that the second-generation mechanism had reliability problems. Specifically, a speck of dust could render a keyboard inoperable, which isn’t a problem in a vacuum, but we generally use MacBooks on Earth.
After collecting and analyzing data from a number of Genius Bars in the United States, AppleInsider found that keyboards were failing at twice as the rate of older models. Salivating lawyers filed class action lawsuits, alleging that Apple knew about the problem and still released the laptops. Apple’s response was to admit no fault, state that the problem affected “a small percentage of keyboards,” and unveil a keyboard replacement program.
Just last week, Apple announced its new, third-generation butterfly mechanism. Apple advertises it as “quieter”—no mention of improved reliability. When it was announced, many people speculated that the new keyboard being quieter was a byproduct of a reliability change, but it was still speculation. Apple toed the party line. The change was to lower the volume, not correct a defect. Noise was the problem.
Then a brave, ignorant, or principled—maybe all three—technical writer confirmed what so many had suspected: yes, the change was designed to improve reliability. A service document, the kind given to Apple Authorized Service Providers, noted, “The keyboard has a membrane under the keycaps to prevent debris from entering the butterfly mechanism. Be careful not to tear the membrane. A torn membrane will result in a top case replacement.”
I realize it’s taken me seven paragraphs to get to the point, but this technical writer deserves our praise. The responsibility of a technical writer is to present relevant information, not bow to the product team or marketing department on whether or not including a fact is acceptable.
Marketing still works, of course, but customers recognize marketing materials when they see them. They realize they need to take them with one or two or six grains of salt, turn their internal bullshit detectors to the maximum level, and parse the content with a trained eye.
Documentation shouldn’t require readers to make that adjustment. It should project honesty and credibility. Labeling a process as “clunky” or “cumbersome” in documentation is fine if the process is clunky or cumbersome. Content should reflect today’s reality. Describing a lengthy workaround for a missing feature is the responsibility of a technical writer, even if the product team is embarrassed that they forgot to implement seamless backups or data migration. No product is perfect, and documentation is not a veneer. Omitting critical information or including marketing-speak destroys your credibility. It makes you sound like a mouthpiece rather than a colleague.
So kudos to that technical writer for doing the job and doing it well. Kudos for reinforcing the trust that readers place in us, and kudos for being the only person at Apple willing to tell the truth.