November 5, 2020

Contrarian in Plain Text


Although the options of What You See Is What You Get (WYSIWYG) editors are initially appealing, they do more harm than good. No discussion of WYSIWYG would be complete without mention of Rachel Andrew’s classic essay Your WYSIWYG Editor Sucks (Andrew, 2011). In it, Andrew argues that Content Management Systems, like Wordpress, should not use WYSIWYG editors. Many of the same points, and more, can be made against WYSIWYG editors for content creation in general

The Case Against WYSIWYG

The most obvious, and plainly stated, reason against WYSIWYG is that content in the modern age is seen in multiple places and formats. As Andrew (2011) puts it, emphasis by original author: “What You See Is What You Get WHERE exactly?” Modern documents are posted to the web, displayed on computer screens, and printed on dead trees for posterity. Copying between formats has the high potential to introduce artifacts or display quirks in different formats. Further, different formats are better for different needs; eg I don’t think anyone actually enjoys reading a PDF in their browser. Worse, copying between formats can introduce errors where one version/format is not up to date or contains wrong information.

When a team, rather than an individual, is generating content, WYSIWYG draws the focus from the content. It is immaterial, or it should be, what font is used when first drafting a position statement, for example. The same can be said for line breaks and page breaks. Yet, you cannot start a MS Word document, or google Doc, without picking some default value for font.

The Alternative

The alternative is to author documents in a plain text format, like markdown, and only once the document is finalized format shift it to required formats. “Markdown is intended to be as easy-to-read and easy-to-write as is feasible” (Gruber, n.d.). Gruber gives an example, on his very site, of how markdown can be used to generate content intended for the web. The same markdown document can be converted to a PDF or even a MS Word file or format. This can be accomplished using Pandoc or tools like it.

This has two major advantages:

  1. When writing, the author, team or individual, can focus on writing and not displaying.
  2. The same source document can be format shifted to various formats for display, archiving, record keeping, and data analysis

By data analysis, it is meant both automated and manual searching through text corpuses, and comparing versions of the same document. The programming community already has sophisticated tools for examining the differences in different versions of the same text file. These tools were originally developed for source code files; but they work equally well for documentation. A common convention when writing documentations, or documents, in this manner is to put one sentence on a single line. Markdown does not interpret a single linebreak as meaningful; so this does not disrupt the final document as displayed. Each sentence, in a thesis or a regulatory document, can be seen as a complete statement; it is semantically equivalent to a single line of code.

The greatest advantage to authoring documents in plain text comes from the easy at which the documents can be placed under version control. Version control tracks changes to versions of text documents. While WYSIWYG editors like MS Word have rudimentary versioning, it is in comparable to the strategies offered by modern version control. Version control allows for the fine tuned control over a collection of documents, not just individual documents. Further, the ability to branch and merge are invaluable to a team working on a collection of documents. Branching allows work to be conducted while maintaining the approved, or official version, in the exact same way code has a production version and a development version. Work can be done on a working branch, and only merged when it is approved by the team, or by the authority the team reports to, eg a board of directors or the full team/committee at a voting meeting.

In conclusion, the advantages of authoring documents in plain text with Markdown should not be ignored lightly.


Andrew, R. (2011, July 27). Your wysiwyg editor sucks.

Gruber, J. (n.d.). Markdown syntax documentation. Daring Fireball.

Like this? Please Share it:

© Steven Malins 2019-2020