pvh / Aug 2022

Our publications follow what we call “academish” voice. We follow a largely academic style in our writing but avoid certain academic tendencies.

Academic Style

• Make no claims without support. If you have made an unsupported claim consider its centrality to your argument. If “many developers agree”, we should be able to link to a source or describe how we know that. If you can’t defend it, you should get rid of it.
• Avoid absolutist language. It’s not “the main problem”, it’s “a problem”. (Unless, of course, you can defend the claim.)
• Be precise and specific with your descriptions. Instead of saying something “feels great”, describe how it feels. Don’t say something “is a problem” unless you describe what the problem is or to whom. If you’re tempted to say something vague because you’re not sure, either do enough research until you’re sure, or don’t say it.
• Avoid hyperbole. Use adjectives to add precision, not to persuade. Claiming “immense benefits” is only appropriate if you have developed a commercially viable fusion power plant. Delete words that are only for emphasis, and keep only those that add substance (e.g. quantify).
• Structure your writing for incremental reading. Don’t bury the lede. A reader should be able to understand the goals and conclusions of an essay by reading the first couple of paragraphs. Individual sections should briefly reiterate any important material and/or link back to where it is introduced. This may feel repetitive at times but aids readers who take several sessions to read a piece or who jump straight to the sections that interest them.
• Give credit to others. Cite earlier work. Link to sources for terms and ideas. Give thanks to contributors, reviewers, and advisors.
• Be humble and transparent about shortcomings and problems. We want readers to build on our work, not buy our product.

Ink & Switch Style

• Assume the reader is an interested generalist. Explain jargon. Academic writing is dense with domain terminology because it assumes readers are “up to date on the field.” Ink & Switch Essays make use of marginalia in what we call “asides” to define uncommon terminology. Concretely, you don’t need to gloss “HTML”, but you should probably gloss “CRDT”.
• Carefully consider section headings. Headings should legibly communicate the shape of the essay and serve as a roadmap for a reader to skip to the part of an essay that’s most interesting to them. Similarly, avoid including unrelated material in a section with a particular title. If a user already knows “How CRDTs Work” then they shouldn’t miss (much) important information about the project by skipping reading that section.
• Embrace interactive demonstrations, animations, illustration, and videos. Sometimes an illustration or demo can offer more clarity on a topic than text alone. As long as the content is self-contained and doesn’t rely on external sources, it should be legible for many years to come and viewable offline.
• It’s okay to share hunches and beliefs as long as they’re appropriately labeled. Don’t be shy about drawing conclusions, just be clear about the degree of confidence you have and where it comes from.
• Ensure content looks good in PDF / printed form. Obviously you lose the elements above, but the PDF version of a paper shouldn’t have giant ▶️ icons obscuring an image. Interactive figures should display a meaningful static view.
• Use “asides” for supportive content and marginalia. Asides can expand on references to other work, link out to related projects, or just share interesting context or historical tidbits.
• Deploy persuasive or emotional writing appropriately. You can be enthusiastic in describing your goals but be modest in how you describe your solutions.
• Keep it classy. We don’t dismiss other people’s work or insult their products. Everything around you was made by someone working really hard on it. If we have found a better way, we should show gratitude to those who helped us realize the path forward and humility about our contributions.