In Praise of the WYCIWYG Editor

Starting out on WP 5.1 for DOS

After the typewriter, WordPerfect 5.1 became my tool of choice for school papers and other assorted random documents. Our first printer at home was letter perfect (I think that was the term) because there was a wheel with protrusions for numbers, letters, and basic characters.

When you sent a doc to the printer, the wheel would spin and strike against a ribbon putting just the right amount of ink where needed. We were a few years from meeting Dan Matrix and his wife Dot, to say nothing of color laser output.

Office 97 lands

That changed in the fall of ‘97. I went from (happily) using WP 5.1 in the computer lab to marveling at the slick interface delivered by Microsoft Office 97 running on my own, brand new Optiplex.

There was even this awesome animated paper clip that would pop up and help you with baffling tasks like writing a letter! I typed a few lines and starting clicking around. Holy Schnikes! I could make the words bigger, smaller, change the font, add italics, color, crazy symbols…

This black magic was WYSIWYG (wizzy-wig) editing: What You See Is What You Get.

The promise was that when you were ready to render to dead tree format, the output would exactly match what you already saw on the screen. Of course, that presumed that you hadn’t done anything crazy like adjusting the margins or sticking page numbers in the footer.

And so it went as I navigated academia and into industry. As it worked out, I spent much more time in drafting and design software than I did in Word.

There were a few times along the way where I tried to develop technical documentation that was to be organized into sections and chapters, presumably across multiple linked *.doc files. All of those efforts fizzled out before I got too far into progressing beyond the basics in Word.

Time for a change

That changed a few years ago. We went through a major migration in our CADD platform and needed to memorialize the new configuration in order to ease the transition. I knew what I wanted: consistent output with multiple styles based on what the docs were describing - monospaced Courier for text configurations, blue italics for UI components to click on, red bold capitals for DO NOT EVER DO THIS!!!!!.

Boy, was that painful in Word. It seemed impossible to get image placement consistently correct.

I had terrible amounts of brain damage trying to get consistent styling and proper numbering across the header hierarchy. As the content grew, it got split out into multiple *.docx files, which meant there was no easy way to cross-reference content across sections and chapters.

The only real option for publishing was PDF, which meant a lot of user clicking to navigate. I tried to make everything better by building a web portal of sorts that linked to the individual chapters and included a primitive change log.

Back to HTML

It had been a long time since I had written any html - almost 15 years. I started the same way as before: hand coding html in a text editor. I had upgraded to Notepad++ by this point, but that was about it.

After doing some research, it seemed like jquery and bootstrap were taking over the world. I eventually strung something together and it worked relatively well, with a lot of copy/pasting and crazy nested <div> elements. Hmmm, I thought… What if there was some sort of templating engine that could streamline and automate all of that HTML generation?

Enter Python

Roughly at this same time, I was starting to learn python. After reading that vim and python were a match made in heaven, I started learning about hjkl and :wq. Learning vim was like dropping TI in favor of an HP calculator. Everything felt crazy-weird for about two weeks, then things got awesome.

As I explored all of the batteries included with python, I started noticing a beautiful consistency with the documentation. It had the structure and formatting of doxygen but didn’t look like it belonged on Netscape Navigator 2.0. What I was seeing was html generated by Sphinx from content written in rST. Could this replace my half-bootstrap, half-Word Frankenstein?

Learning by doing

I wasn’t writing much python at this point, but I had just wrapped up stringing together a macro in object-oriented VBA. I couldn’t get the ship turned towards python fast enough, and here was the perfect opportunity to see if this new toolchain might fit my needs for technical documentation.

If you’ve made it this far into the story, you can probably guess that the answer is a resounding YES.

I could use all the standard directives to basically line up with my requirements and get rock-solid consistent styling across the board. Building up a table of contents was as easy as writing a table of contents in plain text. Cross-referencing was a breeze, and default output to HTML meant that navigation was snappy and efficient.

Best of all, I could use that weird thing called git to track all of my changes and even travel back in time if necessary. Soon thereafter, I found I could get PDF output from the exact same content.

I probably didn’t realize it at the time, but this new tooling provided great separation of concerns - data here, logic there, presentation however and wherever you want it.

Therefore, I am now claiming a new term for this approach to content generation:

WYCIWYG (wacky-wig) - What You Code Is What You Get

A few standard deviations outside of mainstream?

I get it. Word and Google docs aren’t going to disappear tomorrow in favor of terminal emulators and model editing. However, before dismissing WYCIWYG, consider this:

• Lawyers still use Word Perfect due to formatting strictness
• Microsoft project managers are writing docs in markdown and using git for change management
• You can read to / from multiple formats with tools like pandoc
• I recently captured two full days of meeting notes in a single markdown file using VS Code with vim keybindings. It was splendid.
• Have you ever heard “Wow, those styles were so easy to use and track changes stayed nice and tidy even though we had 45 people editing the Word doc simultaneously!”

I didn’t think so.

Conclusion

It’s never been a better time to be on the command line. While I know I won’t ever totally escape WYSIWYG, it’s liberating to have - and utilize - its far superior alternative, WYCIWYG.