Even for a professional writer, long editing sessions are a challenge. Was I actually editing those last ten pages, or did I nod off around page three?
To help make sure I’ve been editing aggressively enough, I use a simple checkpoint rule:
After editing a first draft, the text should be 25% shorter.
Cutting 25% probably sounds like a lot. How does this work in practice? Let’s take a look at two short real-world examples.
Example 1: jQuery Document Ready
From the “How jQuery Works” tutorial, “Launching Code on Document Ready“:
The first thing that most Javascript programmers end up doing is adding some code to their program, similar to this:
window.onload = function(){ alert(“welcome”); }
Inside of which is the code that you want to run right when the page is loaded. Problematically, however, the Javascript code isn’t run until all images are finished downloading (this includes banner ads). The reason for using window.onload in the first place is that the HTML ‘document’ isn’t finished loading yet, when you first try to run your code.
Breaking this down step-by-step:
-
“The first thing that most Javascript programmers end up doing is adding some code to their program, similar to this” — Already I’m not a fan of this intro, as it doesn’t explain to the poor newbie jQuery developer why “most” JavaScript programmers do this.
- “The first thing that” — This is throat-clearing. Instead lead off with, “Most JavaScript programmers…” or more accurately, “Many JavaScript programmers…”
- “end up doing is” — More throat-clearing. Instead, say what the programmers are doing directly.
- “adding some code to their program” — Too vague. Replace with something more specific, like “wrap their code in an
onload function…”
- “similar to this:” — Also unnecessary. Launching into an example already implies “similar to this.” If you do want to have a transition to the example, you can always go with the classic, “For example:”
-
“Inside of which is the code that you want to run right when the page is loaded.” — The first paragraph now already says most of this, thanks to the “wrap their code in an onload function.” The slightly new information is the “right when the page is loaded.” Delete this sentence, but remember that last bit…
-
“Problematically, however,” — Replace with, “Unfortunately,”
-
“… the JavaScript code isn’t run until all images are finished downloading (this includes banner ads).” — Minor stylistic changes: “isn’t run” to “doesn’t run” and “(this includes banner ads)” to “, including banner ads.” Parenthetical statements are a bit harder to parse, so I try to use them only when necessary.
-
“The reason for using window.onload in the first place is that the HTML ‘document’ isn’t finished loading yet, when you first try to run your code.” — Finally, here is the reasoning we were looking for back in the first paragraph. Why do “most JavaScript programmers” use onload? Because they are waiting for the browser to finish loading the document. So let’s say that, and while we’re at it, move the concept up to the top of the section. “To ensure that their code runs after the browser finishes loading the document…”
The revised passage is now:
To ensure that their code runs after the browser finishes loading the document, many JavaScript programmers wrap their code in an onload function:
window.onload = function(){ alert(“welcome”); }
Unfortunately, the code doesn’t run until all images are finished downloading, including banner ads.
Example 2: Facebook API
From the Facebook Graph API documentation for Achievement(Instance):
The achievement(Instance) object represents the achievement achieved by a user for a particular app.
You can read more about achievements here.
An app can always access achievement(instance) associated with their app with an app or user access_token associated with their app. To access achievements for a user for other apps they require user_games_activity permission and to access achievements for the user’s friends, the app requires friends_games_activity permission.
Breaking this down step-by-step:
-
“… represents the achievement achieved by a user…” — The obvious weak spot is the “achievement achieved.” Eliminating this repetition and changing the clause to active yields, “represents a user’s achievement for a particular app.”
-
“You can read more about achievements here.” — A “click here” sentence! Excellent, a freebie. Just link “achievement” above and then nuke this sentence entirely.
-
“An app can always access achievement(instance) associated with their app with an app or user access_token associated with their app.” — This sentence is hopelessly mangled. Without talking to an actual Facebook engineer, my best stab at this sentence is:
- “An app” — Shorten to just, “Apps.” This is just a minor stylistic change.
- “achievement(instance) associated with their app” — Shorten to, “their own achievements.” Since this whole section is about the
achievement(instance) object, it’s unambiguous here to just refer to them as “achievements” most of the time. As a side benefit, it’s not clear what Facebook’s convention is around capitalizing achievement(instance), so using “achievements” sidesteps this style issue.
- “with an app or user
access_token associated with their app.” — Change to, “using an app access_token or user access_token.” The “associated with their app” is implied given the sentence that follows. Also, clarify whether we’re talking about a single type of access token (a user or app access token), or two types of access tokens (a user access token or an app access token). Here, I’m guessing it’s the latter.
-
“To access achievements for a user for other apps they require user_games_activity permission” — Break this off into a new sentence, “Accessing a user’s achievements in other apps requires user_games_activity permission.”
- “To access” — Change to “Accessing.” Another minor stylistic change. The main reason I like it better is that it makes it a bit easier to get rid of the “they” later on in the sentence.
- “achievements for a user for other apps” — Eliminate the double “for” and shorten to, a “user’s achievements in other apps.”
-
“and to access achievements for the user’s friends, the app requires friends_games_activity permission.” — Create a parallel sentence to the previous one, “Accessing a user’s friend’s achievements requires friends_games_activity permission.” Saying “user’s friend’s achievements” is a little dicey, but I can live with it.
The revised passage is now:
The achievement(Instance) object represents a user’s achievement for a particular app.
Apps can always access their own achievements using an app access_token or user access_token. Accessing a user’s achievements in other apps requires user_games_activity permission. Accessing a user’s friend’s achievements requires friends_games_activity permission.
Conclusion
$ wc /tmp/*.txt
5 67 475 /tmp/facebook-orig.txt
3 43 354 /tmp/facebook-revised.txt
5 85 522 /tmp/jquery-orig.txt
5 42 301 /tmp/jquery-revised.txt
18 237 1652 total
There are a couple of takeaways here.
The first is that you won’t reach the 25% by tinkering at the margins, fixing little issues around grammar and wordiness. You need to dive in and rework entire sentences, paragraphs, and sections. Don’t worry — in a first draft you will always, always find sections that you can delete or radically shorten. The 25% Rule is there to force you to do the harder, more important work of rethinking the text.
The second is that the overall idea is not, “Whoever reduces the text the most WINS AT TECH WRITING!” The idea is only that if you are editing a first draft aggressively enough, then you should probably see a reduction of around 25% or more.
In other words, the 25% Rule is just a rough self-check for your edit. If you’ve crossed the 25% threshold, you’re probably doing okay. There are no “extra points” for going further.