Why markup (and Markdown) matter

This is a paragraph. You may be reading this paragraph on your Tumblr dashboard, or your RSS reader, or on the Editorially blog directly. You may be reading this on your tiny laptop, your giant monitor, your phone or tablet, your Kindle or TV or game console. You may have time-shifted this paragraph, and are now reading it in Instapaper or Pocket or Readability. You may be listening to these words via a speaking browser.

Regardless of where or how you’re reading it, one thing is constant: the underlying syntax that delivers the above paragraph — regardless of the device or platform — is HTML:

<p>This is a paragraph. You may be reading this on your Tumblr dashboard, or your RSS reader, or….</p>

On the web, HTML is what your words are made of. How your words are interpreted depends upon the markup that accompanies them. As such, it’s important for people who care about the words to also care about the markup.

But tools for writers make caring more difficult than it should be. Many writing applications still adopt a WYSIWYG (“what you see is what you get”) approach, a habit of the print era emphasizing how text looks instead of what it means. At best, these tools hide the underlying markup; in practice, most of them mangle it in various ways, leading to brittle and error-prone content that may work in one scenario, but is likely to break when read elsewhere. Letting a WYSWIYG editor decide on your markup is like letting a book go to press without reviewing the proofs: you neglect the markup at your own peril.

The good news is that markup is easy. In fact, the “markup” part of “HyperText Markup Language” takes its name from the editor’s act of marking up a text. The basic elements of HTML — paragraphs, headings, lists, and so on — are familiar to anyone who works regularly with words. If you know nothing of HTML but can find your way around standard proofreader’s marks, then you need not learn a whole new way of thinking about text — you just need to learn a new syntax, and a simple one at that.

That said, HTML is designed to be readable by both humans and machines, and the latter requirement means it also tends towards the verbose. It’s a great tool for publishing, but a less-than-perfect one for authoring. That’s where Markdown comes in: recognizing that it’s important to author good HTML, Markdown proposes a shorthand to make authoring more comfortable. Whereas HTML requires a <p> tag before every paragraph, Markdown chooses to identify a paragraph simply by its spatial separation from other text. Whereas HTML requires nesting several tags to create a numbered list, Markdown lets you just number them naturally. A simple conversion tool then translates that shorthand into good, clean HTML, which can be ported to any content management system, anywhere.

HTML above, Markdown below; the latter is much more comfortable for reading and writing, while guaranteeing that the final output will be exactly as you intended.

Put simply, Markdown gives you control over the final HTML without making you write out every bracket. Just as importantly, it relies on familiar shorthand you probably already make use of — asterisks for emphasis and bulleted lists, for example. As an added benefit, it lets you compose text for the web entirely from the keyboard: no knobs to push or menus to hide and reveal. Just type, and focus on the words.

This is why Editorially’s writing environment makes use of Markdown, and why we think you’ll love it. When we first sat down to discuss the needs of content creators on the web today, one of the core concerns was making sure that the content worked, wherever it went. Giving writers and editors purchase over the HTML that described their content was a natural goal. Markdown lets us serve that goal without sacrificing the convenience and sheer pleasure of a minimal writing environment.

But using Markdown doesn’t mean relinquishing the niceties of a visual experience. We’ve built in some lightweight cues to reinforce the underlying meaning of the markup. Wrap a word in single asterisks to denote emphasis, and we can display that word in italic and fade the asterisks back a bit, echoing the default display of an <em> tag. Use numbers to draft a list, and we can enhance that list with a hanging indent. Rather than “what you see is what you get,” the visual feedback reinforces something else entirely: what you see is what you mean.

The editor visually styles the Markdown as you type, reinforcing the meaning of the text.

There was a time when the writer’s job included understanding how many words fit on a page, how many characters could fit into a headline, or how to revise a paragraph to remove a widow. On the web, those concerns have faded, and a new set of constraints — a diverse and distributed publishing system, screens of all sizes, new ways of sharing and collaborating on our work — are ascendant. This makes it an exciting time to be a writer: we’re learning how our words go out into the world, and fortifying them for the journey ahead.

Markdown is not the only way that Editorially will help writers and editors down that path. Stay tuned for more.

Writing a better terms of service

Most people won’t read the terms when signing up for a new service, because most terms are impenetrable and unfriendly to reading, both in design and content. But as a team, we care deeply about the related crafts of good writing and good typography and felt it was important for our terms to reflect those beliefs. So we set out to do the unthinkable: draft a terms of service that we could be proud of, one that would adhere to our high standards for writing in general, while still meeting our important legal obligations.

We think the results speak for themselves (and we’re delighted that others noticed as well). In the process of working on them, we learned a lot — about why terms typically read the way they do, the best ways to adapt and revise them, and which so-called legal requirements are not actually written in stone. Just as importantly, we learned that a little effort here goes a long way: it wasn’t difficult to produce a readable, meaningful contract between us and our users. It took a small amount of time and attention, but we believe that time will be more than offset by the reduced likelihood of misunderstanding, and the chance to build a better relationship with our users.

We’d like to share what we learned, in the hopes that other services may benefit from it too. In fact, since nearly every service kicks off the process of drafting terms by starting with some boilerplate, we’re offering our terms up as a better starting point. As of today, we’ve released our terms under a Creative Commons Attribution-ShareAlike license, so you can use and adapt them as you see fit.

Note that we mean these as a starting point: your service is unique, and your terms need to reflect that. As you adapt these to your own purposes, we offer up the advice that follows. (Note, also, that we are not lawyers, and this post does not constitute legal advice. The very first step in drafting a terms of service is hiring a good lawyer to work on them with you. We’re grateful to our counsel, Gabe Levine, for putting up with our incessant questions as we iterated on our terms.)

Keep it readable

This is the first, most difficult, and most important goal when drafting terms. There is no legal reason for your terms to be opaque or confusing. Approach the writing process the same way you would any other communication with your users: use plain language, and speak like a human. Keep your sentences short and simple. Make generous use of numbered and bulleted lists where possible.

Don’t assume that commonly-used legalese is required; much oft-repeated language is the result of laziness, not a legal mandate. If your lawyer suggests language that’s thick or confusing, ask for clarification about why it’s needed, or what it intends to communicate. Then translate that into language you’d be comfortable using if you were sitting across a table from a colleague or friend.

Reflect the present, not the future

The tedium and legal cost of working on a terms of service can inspire you to include language that covers not only your current feature set, but future releases as well, thus prolonging the document’s lifespan. But don’t be tempted down that path. Your users should not have to agree to terms in the absence of understanding how they relate to the service you provide. At the same time, that feature you’re working on may yet change before you ship it — so the terms you’re planning today are likely to need review and revision in the future anyway.

Rather than trying to “set it and forget it,” assume your terms are an ongoing work in progress, and consider updates and revisions to be part of the process of releasing new features. As an added bonus, communicating updates to your terms in the context of the features they make possible will help your users better understand your goals and obligations to them.

Don’t overreach

It’s tempting to define your company’s rights expansively, so you can experiment and iterate without worrying about whether or not the terms limit your imagination. But the flip side of that convenience is that overreaching has the potential to alienate and offend your users. For example, if your terms cover the ability to resell your users’ content, but you don’t yet have any mechanism to do that, your users are likely to presume your purposes are nefarious. Be especially careful of overly permissive licenses or copyright claims over your users’ content, as these are likely to be met with disapproval (and you probably don’t need them anyway). Claim only the rights which your service needs to operate, and no more.

Provide examples

Abstract legal language, even when translated into more accessible terminology, can be hard to relate to. Provide clear and relevant examples to make those concepts easier to parse.

For example, the Editorially terms include a privacy policy outlining how we may share our users’ personal information. An early draft included the phrase, “we will not share your information with any third parties, except as necessary to provide the services offered.” But that “except” clause, on its own, sounded worrisome; why would it be necessary to share personal information to provide the services? In a revised draft, we added an example to clarify:

We will store your personal information, but will not share it with any third parties, except as necessary to provide the services offered. For example, we may store your personal information along with your files and data on a third party server such as Amazon Web Services.

Examples can clarify otherwise vague promises, and make it easier for your users to understand your intentions.

Don’t annotate bad language

Many terms attempt to annotate otherwise opaque language to make it easier to understand. But such annotations, however well-meaning, only serve to complicate an already complex document. Now, instead of one text, your users have to comprehend both the legal document and the explanatory annotations layered on top of it. If a user’s reading of the original text doesn’t jibe with the annotation, or if either leaves room for confusion, you’re left with a situation significantly more complex than any single document could suggest.

If it’s possible to translate opaque legal language into human readable language, then use the latter as the text of your document rather than simply window-dressing the original language.

Don’t get cute

There are lots of opportunities for fun and clever language in your service; the terms are not one of them. These are serious, legal documents which have consequences for both you and your users. Save the cute for elsewhere.

Refrain from yelling

If you’ve read any terms, you’ve probably noticed the large sections of ALL CAPS language, usually somewhere near the end. The purpose of this offensive typesetting is ostensibly to call the reader’s attention to provisions that have important legal implications. In reality, however, DENSE ALL CAPS IS MORE LIKELY TO DISCOURAGE READING THAN TO INSPIRE IT. We elected to highlight these sections with a yellow background, drawing attention to them without reducing readability.

Draft, get feedback, iterate, repeat

Your terms are an extension of your product, and they can be subjected to the same process for user-centered design as everything else you’re building. Draft, get feedback, iterate, and repeat. Bake in the time to solicit and act on that feedback, and your terms will improve in concert with your product.

Remember, also, that your terms are a reflection of your values: if you care about your users and take seriously your responsibilities to them, it will show. Likewise, if your terms are readable and reasonable, your users will better understand your intentions. It’s been said that a good contract is the basis for trust. We couldn’t agree more.

Introducing Editorially

Most writing applications fall into one of two camps. Old-school WYSIWYG (“what you see is what you get”) tools provide lots of options for formatting and making templates, but they’re bloated and trapped in a model for writing that still assumes paper as its final destination. Underlying these tools is an assumption that’s no longer valid: on a web with hundreds of devices and platforms, and an infinite number of screen sizes — not to mention time-shifting and syndication services — “what you get” is no longer singular.

On the other side, many newer tools happily embrace the underpinnings of the web — trading superficial styles for more meaningful markup. But these same tools’ fealty to a mythical “distraction-free zone” inspires them to lock writers away in small rooms by themselves. In trying to get away from the mess of the past, they make the mistake of assuming that a minimalist writing environment must also mean a hopelessly solitary one.

Neither of these approaches fully respects the actual writing process, which oscillates between the quiet of the writer’s private cabin and the hum of the editor’s markup. Good writing requires both the safety of the former and the constructive criticism of the latter. Moreover, the web breaks from the past both structurally and socially: swapping ink for HTML and the postal service for the network. Writing can benefit from both.

Where we come in

It’s with all this in mind that we came together to make Editorially, a new collaborative writing and editing platform. We believe that the web is not merely another distribution pipeline, but a unique and deserving space for both reading and writing. Our goal is to support and encourage that writing process — from the first flash of inspiration all the way through to publication, and at every point in between.

Editorially achieves this goal in many ways: a Markdown-based writing environment lets you focus on the words and create clean markup easily; collaboration tools let you invite friends and trusted colleagues to review or edit your work; a document version system lets you mark points in a document’s history and compare versions to see what changed; notes and activity feeds encourage you to reflect on your work, for yourself and for others; and discussion threads recognize that the conversation around a text is just as important as the text itself.

And we’re only getting started. This is not just another text editor: it’s an ecosystem for the writing process. We’ve designed a space that brings you closer to both the words and the people — the only things that matter.

Why us

Together, the team behind Editorially have worked as writers, editors, publishers, designers, and developers; we’ve shipped products, books, and magazines, and enjoy debugging code as much as a good copyedit. We know the pain points of working collaboratively first-hand. We also know scratching your own itch is not the end-all of a product strategy, but the beginning. Working with advisors from every walk of the publishing world — from age-old institutions to scrappy startups — we’ve distilled everything we know about writing and editing into a tool that will change the way you write — for the better.

What’s next

We have a lot more to share in the near future. In the meantime, subscribe to this blog, follow us on Twitter, or sign up to be invited. The doors will be opening soon.