The Scripting Editor Tells All
Summary: Dia Reeves, aka the Scripting Editor, has some fun talking about working on the Hey, Scripting Guy! Blog.
Microsoft Scripting Guy, Ed Wilson, is here. Today we have a guest blog post from my editor, Dia Reeves…
Hello to all you Windows PowerShell scripters and fans of the Hey, Scripting Guy! Blog! I have been editing and publishing this blog since 2011, and I thought it would be fun to write a post that helps you understand my part in our process and share some stats about our blog.
Maybe I will let Ed edit and publish my post!
Well, maybe not…
Although I have been a technical editor for 14 years, I don't mind admitting that I do not consider myself very technically oriented. In my only programming class, I sat in horror as all the other students celebrated with glee when "Hello World!" appeared on their screens. I finally summoned the instructor to help me. "You're missing a comma…See? Right here," he drawled.
Are you kidding me? Missing a tiny little comma? What kind of crazy person would want to do this all day, every day? (…she asked, winking at all you dev dudes and dudettes.)
Of course, the irony is that I now thrive on missing and misplaced commas…
misused semicolons…
misspelled words…
misplaced modifiers…
Stop me!
So I chose the path of an editor, not a dev.
The true value of an editor is mysteriously hidden behind the scenes. My main goal is to make writers look good with no one knowing I was there. For fun, I marked up a paragraph from a blog post so you can see the types of changes I make without the writers ever knowing (sshhhh):
This example simply needed a little punctuation and a little clarification, but publishing it as written would not have been the best plan.
Hey! I have a great idea! What if we could package simple issues such as those in a Windows PowerShell command? No one would ever need an editor again. Enter the best cmdlet ever, Get-Editor, and its nifty parameter -ClearConciseConsistent:
PS C:\> $edit = Get-Editor -ClearConciseConsistent
But alas, such a command could never replace the total logic in an editor's head. What the heck am I looking for aside from proper spelling, capitalization, and punctuation? The editor's head sees fascinating factoids such as these:
- Blog writers like to use "so" and "now" a lot. I kill hundreds every year.
- Have we said anything that could possibly offend anyone in the world?
- Writers like to use "just" when they really mean "simply" or "only."
- Do you know that our style dictates using "following" or "under" instead of "below"?
- "Since" has a different meaning than "because, and "once" does not mean "when" or "after."
- Although "PowerShell" is common terminology amongst the community, we are still obligated to use "Windows PowerShell" in our documentation.
- Who else really cares if that S in PowerShell is capped?
- Are the cmdlets, parameters, and objects formatted correctly?
- Does every sentence make sense? Sometimes writers ramble, and with many readers in countries where English is not the first language, the text needs to be clear and concise.
If all this sounds very mundane and unimportant to you, it should! Most of this is stuff that writers (or readers) should not have to concern themselves with…
One moment, please…
"Yes, Ed?"
"This just goes to show why having an editor is a good thing. Even when editors are writing, they can accidentally end a sentence with a preposition from time-to-time."
"Thanks for the excellent feedback, but I think I'll exercise my writer's prerogative and leave it."
Now where was I? Oh, yes…A writing hat is far different than an editing hat. Writers should feel free to ramble, knowing that a good editor will sort it out behind them.
Traditional writing and editing practices are a back and forth dance. The writer submits a document and the editor sends it back full of suggested changes. The writer takes the good and ignores the bad, then sends it back to the editor with more suggestions. And around it goes…
This collaborative effort is so much fun! But it is very time consuming, and things are moving fast in the computing world, including the world of Windows PowerShell. We post a blog and a PowerTip every day of the year, so it is easy to see that this traditional format will not work. Because we have worked together for several years and Ed trusts me (Ed added that phrase), in our model, Ed tosses me an article, and I edit and publish it. No reviews involved.
Editors also act as the writer's first reader. I provide a fresh set of eyes for a document that has been re-read and rewritten to ad nauseam. For example, check out this little surprise that I found in a script we were going to post. Every one of you dev types knows that the writer was exhausted by the time he wrote this, and he exchanged the values for .People and .Eater in the output:
He owes me dinner for catching that one.
Here is the user interface of the Telligent tool that I use to publish our blog:
It looks straight-forward enough, right? I dump in the text from the edited Word doc and the tool magically spits out a webpage. But if everything is not input appropriately, the formatting can be funky and the images won't be sized correctly. Don't even mention that the publication date might not be set correctly, or that clicking an improperly set link can totally engulf the screen with a new site.
Ed is a brilliant writer and he is taxed with coming up with two posts per day. Why should he have to deal with this tool? Luckily, I love messing with it. So he can focus on writing.
Did you know that publishing the Hey, Scripting Guy! Blog 365 days a year was originally classified as an "experiment"? No one knew if there would be interest in a daily blog about Windows PowerShell or if there would be enough content to write about on a daily basis.
But as the world of Windows PowerShell grows, so does the information Ed shares in this blog. In fact, everything is growing so fast that he has enlisted the help of many guest bloggers. I have been lucky to also edit the works of brilliant authors such as Sean Kearney, Richard Siddaway, Boe Prox, the Scripting Wife, and a variety of other Honorary Scripting Guys and guest bloggers.
The Hey, Scripting Guy! Blog has grown to be the number 1 blog on MSDN and on TechNet. Here are some interesting stats from our July 2014 statistics compilation:
- We had over 990,000 page views this month.
- In January 2014, we had 2,096,293 page views!
- The most popular article for the last 12 months is Use PowerShell to Replace Text in Strings. Even though it was published in March 2011, it received over 109,000 hits between January and July this year. I imagine that after this post publishes, it will have even more!
- Close to 50% of our readership comes from outside countries where English is spoken as the first language.
- Our unique visitor stat is up by 80,000 readers since this month last year.
Of course, I would like to attribute this growing popularity to excellent editing, but the main truth is that Ed has found a perfect formula for teaching people about Windows PowerShell in easy-to-read snippets and examples. I think we can conclude that our "experiment" has been successful.
If you are thinking that one reason for me writing this post is to illuminate the value of editing, you're right! A writer without an editor is like a doctor without a nurse, an anchorwoman without a cameraman, a rock band without a drummer. In today's world of instant publishing, anyone can write and publish a blog, but will people want to continuously read it? It needs to be clear, concise, and consistent. And guess what? Those are the three tenets of good editing!
~Dia
Thanks, Dia! This was fun.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy
Light
Dark
0 comments