Jim Lynch Codes
  • Blog
  • About Jim

Writings about one coder's stories & experiences.

Proofreading with JProof

12/15/2015

0 Comments

 
Let me begin by saying that I don't like reading grammar mistakes. To me, reading blatant errors shows a lack of intelligence and casts doubt on the validity of the claims in the text. However, much like coding, I believe that writing should be an organic process where you plop your thoughts down in words and then refactor it later. With code, however, you have a compiler to check your work. For word processors like Microsoft Word or Google Docs there is no compiler to run the text through and reveal grammar mistakes with the same level of detail as a skilled proofreader (note to self- this could be good project). These programs love to tout how they have grammar checking engines, but it seems that at the moment human proofreading is the best method for catching and fixing the most errors. 
In the past when I have written blog posts and had them proofread it happened a few different ways. When I worked at an advertising company that I won't name, there was an "article master" who would just change things and throw the article up on the web. I would many times find errors in the published post, sometimes ones that were added by the proofreader! For this reason I think it should always be the original author's call to make changes to the document. The proofreader gives advice on which things need changing and how to change them. That's all. 

How then, should the proofreader give the author his suggestions? How can he say it in such a way that it is clear, succinct, and doesn't require unnecessary extra effort from either party? I've devised a method here that I believe is succinct and clear. Once both parties are aware of and agree on this common notation then they can easily communicate three things about each suggestion:
  1. Where the offending piece of text occurs in the article
  2. A suggested replacement piece of text that.
  3. (Optional) Extra information or comments.
    ​
Let's get into the details. I've fabricated the examples here, but pretend I'm pulling these offending pieces from a real article that I am proofreading. I like to make a new document in MS Word or Google Docs and name it "[Article Name] JProof". Now, I'll write the first offending piece. We begin with a double dash. Using a single dash sometimes causes awkward automatic indentations in some text editors so I use a double dash. Here's an example (keep in mind that the carriage returns are just for readability in this blog article):
-- Michaels brother din't attend
the neighborhood high school. 
Now, we want to make a suggestion for how this should be changed. Note that there are many possible suggested ways to change it, but let's just give one. To show a distinction between the text that is the offending piece and the text that is the suggested replacement text we put an arrow simple. In many word processors simple typing "dash, dash, less than sign, space" will automatically create a small right-pointing arrow. If it doesn't transform into a nice arrow, the less pretty set of characters --> still creates the appearance of an arrow facing towards the right. We can then type a suggestion. Since the offending piece begins with "-- " it can be nice to begin the suggestion text with three spaces so that the two pieces of text are vertically aligned.
-- Michaels brother din't attend
the neighborhood high school. 
   Michael(')s brother di(d)n't attend
the neighborhood high school. 
Notice that the edited parts, here they are additions, are encased by parentheses. This is to highlight to the original author looking at it which parts were changed. Without these, it becomes a bit of a scavenger hunt for the original author to find small things like apostrophes and commas, or even worse; the original author could skip over them completely and the mistake offending piece continues to live on in the article. 

Now suppose we want to give another suggestion. Maybe we like the word don't that think it works here, but we know the original author likes "do not". We can offer another suggestion by using two pipe symbols, ||. This is a common programming symbol know as the logical OR operator​. Here we are saying that either of these suggestions could replace the offending word. 
-- Michaels brother din't attend
the neighborhood high school. →
   Michael(')s brother di(d)n't attend
the neighborhood high school. ||
   Michael(')s brother did not attend
the neighborhood high school.

I've found that there can be times where I want to explain my suggestions. Sometimes I want to defend my suggestion, and sometimes I want to highlight some specific grammar rule that I have in mind when making the suggestion. Borrowing again from programming, I like to use the double slash to denote the line as a "comment line". The comments can go before the offending piece line or after the last suggestion's line. 
// Possessive should use 's
-- Michaels brother din't attend
the neighborhood high school. →
   Michael(')s brother di(d)n't attend
the neighborhood high school. ||
   Michael(')s brother did not attend
the neighborhood high school.
// I know you do not, but don't sounds better.
The above text here is what I call a suggestion block. A suggestion block consists of the offending piece of text, suggestions to replace it, and any comments regarding either the offending piece or the suggestions. Notice that there are no spaces between any of these lines. A space should go after the last line in the suggestion blocks so that the empty line itself separates each suggestion block. Here's how it might look with another suggestion block:
// Possessive should use 's
-- Michaels brother din't attend
the neighborhood high school. →
   Michael(')s brother di(d)n't attend
the neighborhood high school. ||
   Michael(')s brother did not attend
the neighborhood high school.
// I know you do not, but don't sounds better.

// Starting an independent clause. Use a comma.
-- Archie wants food but he just ate lunch. →
   Archie wants food(,) but he just ate lunch. 

It's a very super simple system, and if don't want to use fancy things like MS Word's "with comments" then you might give this a try. 
0 Comments

Your comment will be posted after it is approved.


Leave a Reply.

    ​Author

    Picture
    The posts on this site are written and maintained by Jim Lynch. About Jim...
    Follow @JimLynchCodes
    Follow @JimLynchCodes

    Want FREE access to
    my daily stock tips 
    ​newsletters??
    Sign up here:

    - Triple Gainers
    - Rippers N' Dippers
    - Growingest Growers
    ​

    Categories

    All
    Actionscript 3
    Angular
    AngularJS
    Automated Testing
    AWS Lambda
    Behavior Driven Development
    Blogging
    Business Building
    C#
    C / C++
    ClojureScript / Clojure
    Coding
    Community Service
    CS Philosophy
    Css / Scss
    Dev Ops
    Firebase
    Fitness
    Flash
    Front End
    Functional Programming
    Git
    Go Lang
    Haskell
    Illustrations
    Java
    Javascript
    Lean
    Life
    Linux
    Logic Pro
    Music
    Node.js
    Planning
    Productivity
    Professionalism
    Python
    React
    Redux / Ngrx
    Refactoring
    Reusable Components
    Rust
    Security
    Serverless
    Shell Scripting
    Swift
    Test Driven Development
    Things
    TypeScript
    Useful Sites
    Useful Tools
    Video
    Website Development
    WebStorm
    Writing

    Archives

    February 2021
    January 2021
    October 2020
    September 2020
    May 2020
    April 2020
    February 2020
    January 2020
    December 2019
    October 2019
    September 2019
    August 2019
    July 2019
    June 2019
    May 2019
    April 2019
    March 2019
    February 2019
    January 2019
    December 2018
    November 2018
    October 2018
    September 2018
    August 2018
    June 2018
    May 2018
    April 2018
    March 2018
    February 2018
    January 2018
    December 2017
    November 2017
    October 2017
    September 2017
    August 2017
    July 2017
    May 2017
    April 2017
    March 2017
    February 2017
    January 2017
    December 2016
    November 2016
    October 2016
    September 2016
    August 2016
    July 2016
    June 2016
    May 2016
    April 2016
    March 2016
    February 2016
    January 2016
    December 2015
    November 2015
    October 2015

    RSS Feed

  • Blog
  • About Jim
JimLynchCodes © 2021