Writing

If you do any sort of technical writing on WordPress, you have likely run into the wonderful little quirk of it turning your lovingly formatted double dashes '--' into singe em dashes. Rather annoying.

To add insult to injury, the silly thing shows them as double dashes in the editor, but then renders them as em dashes when viewing the post, making it next to impossible to know what is going on.

I thought I had it fixed at one time, but apparently the behavior snuck back in. I finally got tired of writing "those are two dashes not one" all over the place and went in search of a better answer.

Lo and behold I found one. Peter Cooper had the same problem and figured out how to take care of it. You can see his post here. His is for WordPress 2.5, but it also works for 2.8.x. I have combined his directions along with some info from the comments on his post here just in case I need it again and can't find it :)

Update: After I posted this, one of my friends on twitter, Chris John Riley, offered up another option. Add an HTML comment with just a space between the dashes. You will have to do this in the HTML view instead of Visual view of the editor. It will look like this:

-<!-- -->-

As I said to him, definitely less intrusive, although, with the method below, I just double dash away and don't worry about it :)

Thanks Chris!

WordPress has a built-in function called wp_texturize(). The purpose of this function is to make your beautiful prose lovely to look at too. :) Unfortunately, for those of use who do technical writing, it also completely mucks up some of our stuff.

To stop this from happening you need to edit the functions.php file in your current theme. This file is in your wp-content/themes/<your theme> directory.

All you have to do is add the following three lines to the end of the functions.php file.

<?php remove_filter('the_content', 'wptexturize'); ?>
<?php remove_filter('comment_text', 'wptexturize'); ?>
<?php remove_filter('the_rss_content', 'wptexturize'); ?>

These lines tell WordPress to quit mucking with punctuation in the main content, comments and rss feed. If you want to allow it to do so in any of the three, just omit the appropriate line.

Here is my functions.php file for reference:

<?php
  // Current version of K2
  define('K2_CURRENT', 'hidden cause you don't need to know');

  // Is this MU or no?
  define('K2_MU', (isset($wpmu_version) or (strpos($wp_version, 'wordpress-mu') !== false)));

  // Are we using K2 Styles?
  define('K2_CHILD_THEME', get_stylesheet() != get_template());

  // WordPress compatibility
  @define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' );
  @define( 'WP_CONTENT_URL', get_option('siteurl') . '/wp-content' )

  /* Blast you red baron! Initialise the k2 system */
  require_once(TEMPLATEPATH . '/app/classes/k2.php');
  K2::init();
?>
<?php remove_filter('the_content', 'wptexturize'); ?>
<?php remove_filter('comment_text', 'wptexturize'); ?>
<?php remove_filter('the_rss_content', 'wptexturize'); ?>

One final note, this also affects all other punctuation changes, so you won't get smart quotes, etc.

-Kevin

{ 0 comments }

In this post I offered three tips on writing that make it easier for your reader. Someone anonymously left the following comment.

Is this like the April 1st-type advice? Clearly, these tips are about writing for rejectees from “Are you smarter than a 5th grader?”…. Come on!

Not the most constructive comment, but he does bring up a point I want to address.

Writing in a clear, concise, easy to read, and easy to understand manner is not a judgment of the intelligence of your reader. It’s about making something less complicated than it needs to be. It’s about making it easy for your readers to read and internalize.

Can your readers understand long sentences? Of course they can, but are they willing too? Can you banish white space? Sure, but is that in your reader’s best interest? Can you use your encyclopedic vocabulary? Yup. But “big words” would have worked in the last question just as well.

Shorter sentences, shorter paragraphs, and common language do not mean dumbing down your writing. It means making the information you are trying to share easier to get at for your reader. That's why you are writing in the first place isn't it?

Kevin

{ 1 comment }

Are you wearing your readers out?

Are you making it hard for us to read what you have to say?

Are you making it hard for us to understand what you are trying to tell us?

Last week I attended a class called "Customer-Focused Writing." Don't go away yet. Customer in this case means whoever is reading your writings. It was presented by Ben Shank of Writing Consultants, Inc. The class was great and I learned quite a few things.  I'd like to share three of them with you.

  1. Keep your sentences short.
  2. Keep your paragraphs short.
  3. Keep your words short.

There, go forth and capture readers!

Heh. Okay. I have a little more to say about each tip.

Before we start I would like to mention what kinds of writing I am talking about. Every kind . Emails, memos, letters, long reports, and blog posts.  They all can benefit from these three suggestions.

Keep your sentences short.

There have been many studies done on sentence length. A quick Google search for "sentence length" will return many opinions on the subject. Some of them about prison sentence length, but we're not going to get into that.

What is the idea that keeps turning up? You got it. Keep your sentences short. Sentences of 15-20 words are easier to read. Over 25 words and we often just give up.

Short sentences keep your reader moving.  We don't have to keep re-reading everything to get the thought or idea you are trying to get across. Short sentences also help establish a pace. Think about books that you have read quickly. I bet they didn't have huge sentences in them.

Keep your paragraphs short.

If keeping sentences short helps capture a readers attention, what do you think long paragraphs will do? Scare em' half to death more than likely. What is short? Five to six lines. Since taking the class, I have been paying close attention to my reading habits. Let me tell you what I have noticed.

I am less likely to want to read a piece that is one huge paragraph. As advertisers and marketing folks have said for years, white space is important. Frequent breaks as we read let us digest the information being presented.

Pay attention over the next few days.  Watch for large paragraphs and see if you prefer them to shorter ones.

Keep your words short.

We have a theme going here, don't we? Why use the word 'utilize' when 'use' works just fine. Why stick a bunch of five syllable words in your writing when they are often not needed.

Some will say, "I do a lot of technical writing. I have to write long sentences and use long words." In most cases, you don't. Sometimes you do. Sometimes the only word that will work is a long one. Go ahead and use it. But, only if you really need to.

Leave the monster vocabulary at home unless your goal is to show how many big words you know. Your reader doesn't really care. They just want the information you are trying to give to them. Don't make them pull out the dictionary just to read your stuff.

A few bonus tips.

Good titles are vital. They are what first grabs your readers attention.

Good opening are even more vital. They keep the writers attention. In a lot of cases, the opening is the only part that will get read. If you really want them to know something, get it in there early.

Finally, good closings are vital.  They help cement what you are trying to say in your readers mind.

Use short words, write short sentences and keep your paragraphs short too. I promise you that your readers will appreciate it.

Kevin

PS - If you want to contact Writing Consultants, here is their email address mail (at) writeconsult (dot) net. I have no affiliation with them other than being a satisfied student.

{ 4 comments }