Wednesday, June 4, 2014

Reformatted Writing

A short observation that I sometimes use to my advantage: It helps me greatly if I write something in one format, and then look at it in some reformatted view, before finally distributing it publicly. This tends to dredge up a number of subtle errors or weaknesses which I otherwise can't see. In some sense it gives me "fresh eyes" to really read the draft from a new perspective (as opposed to one's memory blocking reception of what's actually on the page). In this sense we might say that "what you see is what you get" (WYSIWYG) is actually a hindrance instead of a help. A few cases:
  • Blogger. Editing blog posts here, one uses a rich-text editor that is different from the final HTML markup on the site. One clicks "preview" to actually see it reformatted as it will appear on the Blogger site. Something that happens occasionally is that I might have a duplicated "the the" (or something) across a line break, such that I don't initially see it; when the paragraphs and lines get moved around in Preview, I can catch this much more easily. More generally, I can pick up on weaknesses in sentence structure and places I can clarify much more easily in the second view perspective.

  • Lecture Extracts. For a couple of years now I've been providing one-page review guides to students in all of my math classes. I accomplish this by copy-and-pasting all of the special defined terms and procedures in my lecture notes to the review sheet. When I did this, the surprising side-benefit was that I discovered a lot of those definitions had varying formats, tenses, or parts-of-speech, that looked sort of ridiculous when lined up next to each other -- and then I could go back and fix them throughout my class lecture notes. (Arguably you could say this is bad practice due to data duplication; anytime I make changes in my lectures I have to edit the review sheet in parallel. But it turns out that this is not a burdensome task.)

  • Java Code. Just recently I've committed to formatting all my personal coding projects in the javadoc format (special comments that can be parsed out automatically to external documentation). This required a change in style that I thought would be irritating, but was much less painful than I expected, and more than compensated for by the benefits. Again, if I write my code once and then generate the documentation and look at that, I'm finding there's a whole lot of places I can improve on variable names, method names, comments on use, etc. Looking at it from the perspective of a true "outsider", with only the cues someone would start with to theoretically get into my code, gives my end product much greater depth and robustness.
So in summary: Write once, view in a totally different format, and then edit. Results are improved to a surprising degree.


2 comments:

  1. I just stumbled across your blog the other day and have been reading through it, and your description of previewing things in Blogger really struck me, as it's something I've noticed myself doing more and more in the past six years of writing a personal blog. I feel like it's helped my writing a fair bit as well, as I now routinely send any prospective post through several (sometimes many) cycles of writing, reading the Preview version, and rewriting. I even used it on this comment just now to spot a spelling error. :)

    ReplyDelete
    Replies
    1. That's great! Glad you've had the same experience, very helpful. :-)

      Delete