May 18, 2018

Writing to be read

There is a common struggle in the writing and maintenance of documentation, checklists, emails, guides, etc. Each provides immense value; a document may be the key to an important process. The goal is to remove barriers -- to encourage understanding and correct application of what has been noted -- without requiring a change in the character of the reader. That is, expect reading to be difficult and people to be lazy. Don't make things harder for your reader than need be.

Ignoring imperfections in the ideas transcribed into writing, there are a few particular aesthetic approaches I take to (hopefully) make my notes more effective. These ideas have been influenced by readings on writing, psychology, and user experience. In particular, I recommend On Writing Well, Thinking Fast and Slow, and Nielsen Norman research.

Language correctness

Spelling and grammatical correctness are low hanging fruit. They are easy to achieve. Use full sentences, use punctuation, and capitalize appropriately. But don't be a grammar stickler unreasonably; language is flexible and always changing. Don't allow anyone the opportunity to take your work less seriously by screwing up the basics.

Structuring sentences and paragraphs

Keep your sentences short. And avoid run on sentences; they are always difficult to parse. If you use more than two commas in a sentences (aside from in lists), the sentence is terrible. Split it up. Commas are often used superfluously. Don't do that.

Remember that if a comma separates two sentences, you can separate them into two sentences with a period instead. And if you ever have a list containing another list, separate the outer list with semi colons instead of commas to provide better differentiation.

Keep your paragraphs short too. In primary school you may have learned to use 5-8 sentences per paragraph. Don't do so needlessly. 3-5 sentences can be perfectly appropriate. As both sentences and paragraphs get longer, they appear more intimidating and can discourage readers from continuing.

Visually speaking

Make your line height 120-145% the height of the font. Increase the spacing between lines in a paragraph to make the paragraph less dense and more friendly.

Keep contrast high. Don't put very gray (or colored) text on a white background.

Additionally, a number of studies suggest that limiting the width of text increases readability. For best results, limit the width such that 50-75 characters appear per line of text.

Don't put checklists in paragraphs

If a document describes concrete steps that should be followed exactly and can be reasonably summarized, don't hide the steps within paragraphs of text. Instead use an ordered or unordered list to clearly enumerate the expectations. You can't expect a checklist to be followed when it is hidden within the sentences of a paragraph.

Structuring sections

Any document (regardless the type) longer than 3-5 paragraphs should be broken into sub-sections with summarizing headers to aid scanning. Use the HTML id attribute to allow a direct link to a particular section in a long page. If the page has more than two sections or vertically flows beyond a single screen, consider adding a table of contents at the top of the page to allow the reader to find the exact section she needs.

Visually speaking

Don't put large headers immediately next to each other. It is disruptive to have multiple lines of large text.

I almost completely avoid Github Markdown's h1/# tag because it is just too large and jarring relative to the rest of the text. It is often best for the flow of a Github Markdown document to stick to only h3-h4/###-#### tags for headers, using the h2/## tag for the document title.

In summary

The aesthetic flow of a document can help or hurt the experience of a reader consuming it. Good aesthetic "sense" in this regard can be boiled down to a few methods that primarily revolve around simplifying structure and facilitating the rewarding feeling of progress as a reader reads.

Writing is difficult and takes time to evolve helpfully. The dividends are paid when process is better followed and questions are readily clarified in writing without further human intervention. It is incumbent on those writing and maintaining to organize effectively and see confusion of the reader as fault of the document, not fault of the reader. It is easier to change something yourself than to expect others to change to accommodate you.