ITauthor

[This post is out of date. For a better method, see this post. - AC, 22 August 2009]

Writer River – the collaborative list of links to tech-writer-related online content – has changed slightly.

You can still post links to it directly, but you can now also syndicate content to the site from your blog. This means that you can produce you own list of things you’ve read and found interesting, publish it on your blog with an accompanying RSS feed, and have those items also appear, alongside everyone else’s, on Writer River.

Why would you want to do this?

There are a few reasons why this might be something you’d like to do.

1. If you maintain a website, you might be interested in getting as many people to visit your site as possible. One way this can happen is through trackbacks (automatically generated links that appear on blog B when a post is published on blog A that includes a link to blog B). If you add items of interest directly into Writer River, the trackbacks will lead back to Writer River. If you list those interesting posts and articles on your own site, the trackbacks will lead people back to your site and boost your numbers.
2. You might just like to have your own list of the things that have interested you, all listed together on your own site. Now, because of the way Writer River is designed, you could already do this by going to the page on Writer River that lists just your posts (you can find this by clicking your name in the list of authors), and grabbing the RSS for this page (e.g. my old list is currently still there at: http://writerriver.com/author/alistair-christie/feed/) and then taking that and publishing it on your own site. RSS stands for Really Simple Syndication and that’s what it’s for: allowing content to be published in one place and syndicated out for publication in lots of other places. However, if you’re a blogger, it seems weird to post items somewhere else in order to get them to appear on your own site. Better to post to your own site and have that content crop up elsewhere (according to whoever wants to pick up your feeds and use them as they were intended to be used).
3. Doing things this way round means that when a Writer River reader, like myself, clicks an item link at Writer River they are transported to your blog, which gives them the context of who it was who found the thing interesting. The down-side to this is that there’s an extra step in there that people won’t be expecting. You’d expect, when you see something that looks interesting and click you click it, to be taken straight there to the original source, but instead you’re taken to the full version of the reference (e.g. a mini post on itauthor.com) and from there you can click through to the original article. This is a bit disorientating and confusing at first, but it does at least reveal something more about the poster, and it clicks up another hit on the poster’s website.

So how do you do this?

The very, very short and sweet version is:

• Produce an RSS feed containing your reading list
• Tell Tom Johnson (the creator/maintainer of Writer River) about the RSS feed. 
  Tom then adds it to the list of feeds that are aggregated into Writer River.

There are a number of ways you could create your RSS feed. The way I’m going to explain uses categories in a WordPress blog. You could equally well use WordPress tags. You could use another type of blog. You could even manually update a hand-crafted RSS file, if you felt so inclined.  

The basic steps for the WordPress method are as follows:

1. Within your WordPress blog, create a new blog category that you’ll give to all your reading list posts. You can call it anything you like (e.g. “What I’m Reading”) – all it’s used for is to collect together mini blog posts that are simply references to something interesting you’ve been reading. You need to be able to separate these out from your other blog posts so that you can display them separately as a reading list.
2. Alter your home page so that these reading list mini posts don’t appear there. They’re going to be listed separately so there’s no point putting them on the Home Page, and if you don’t exclude them you run the risk of alerting subscribers several times about the same reading list entry.  
         
   To exclude a category from your home page, first get the ID number of the category you want to exclude. You can find the category number by going to your Categories list in the WordPress admin pages, clicking the link for a category and looking in your browser’s address bar for the ID number. Make a note of this.
        
   Next, go to Appearance > Editor and open functions.php. Add the following function (changing 34 in this example to the number of the category you want to exclude):
        
   

   function exclude_category($query) {     
       if ( $query->is_home ) {      
           $query->set('cat', '-34');     
       }    
       return $query;     
   }     
   add_filter('pre_get_posts', 'exclude_category');

   (Source: http://blogmum.com/2009/04/how-to-exclude-categories-from-the-home-page-of-your-wordpress-blog/.)

3. Add a couple of posts about things you’ve read recently.
4. Go to the “What I’m Reading” category on your blog (assuming that’s what you called it) and check you’ve got an RSS feed that lists the items you posted. You do this in WordPress by adding /feed to the end of the URL for the category (for example, my feed is http://www.itauthor.com/category/what-i-am-reading/feed).
5. Now, with the web page version of the RSS feed displayed in your browser, right-click the page and choose to view the source code for the page. 
         
   This will show you the XML that produced this page. This is the RSS feed itself and, after a collection of details about the feed itself, it should contain a couple of item elements: one for each item on your list. Each item element should look something like this: 
          
   

   <item>
      <title>Fascinating Blog Post</title>
      <link>http://www.yourblog.com/path/to/this/particular/blog/entry/</link>
      <comments>http://www.yourblog.com/path/to/this/particular/blog/entry’s/#comments</comments>
   
      <pubDate>Sun, 28 Jun 2009 19:31:13 +0000</pubDate>
      <dc:creator>Your Name</dc:creator>
      <category><![CDATA[What I'm Reading]]></category>
   
      <guid isPermaLink="false">http://www.yourblog.com/?p=3926</guid>
      <description><![CDATA[Fascinating Blog Post. This is a fantastic read. You’d be mad not to 
   have a look [...]]]></description>
      <content:encoded><![CDATA[<p><a href="http://www.fascinatingblog.com/path/to/source/article">
   
   Fascinating Blog Post</a>. This is a fantastic read. You’d be mad not to have a look.</p>
   ]]></content:encoded>
      <wfw:commentRss>http://www.yourblog.com/path/to/this/particular/blog/entry’s/feed/</wfw:commentRss>
   
      <slash:comments>0</slash:comments>
   </item>

            
   The bits that get used on Writer River are the title, which is linked to the URL in the link element (i.e. the individual blog post on your blog) and the the contents of the description element (which are an abbreviated, plain text, version of your post). 
        
   The bit you’ll display on your blog are the contents of the content element, which contain the full text of your post, including any links, images, etc.
6. Copy your feed URL (e.g. http://www.itauthor.com/category/what-i-am-reading/feed) and email it to Tom Johnson asking him to add it to the Yahoo Pipes syndication aggregation he’s got set up for Writer River.

Tips

• Make sure the style of your reading list content doesn’t stray too far from the sort of thing that’s already on Writer River. 
• Don’t post too many items. Writer River works best as a “Best Of” site – so stick to posting just the most interesting things you’ve read. Please don’t just post everything you’ve read!

Other things you can do

• Create a feed on Feedburner.
        
  This isn’t necessary, but it adds a useful element of indirection. This might be useful down the line if your feed URL changes because if you promote the Feedburner version of the feed, rather than the original, then you just need to change the URL details at Feedburner and your syndications won’t break.
        
  It also provides a way of gathering statistics about how your feed is used.
• Create a category template for your “What I’m Reading” category.
     
  Again, why would you want to do this. Well if you don’t then your reading list, with it’s mini blog posts, will have to look like all your other categories. However (following Tom Johnson’s lead on this) I wanted to list my reading list without titles. The reason for this is that the title is linked to the individual page and I don’t want people going from the reading list to an individual reading list post: that would be really annoying for readers. What I wanted was that, if someone is interested in an item, they click the link and go to the web page I’m referring to. So, to do this, you need to be able to use a different template to display just this template.
         
  To create a category template, create a PHP file in your theme’s directory called category-n.php where n is the number of your “What I’m Reading” category. As noted above, you find the category number by going to your Categories page, clicking the link for a category and looking in your browser’s address bar for the ID number.
• Make a template that’s used to display single pages where the post belongs to a specific category.
           
  If you’ve got a category-specific template for your reading list you’ll probably want a category-specific single-post template, so that, when someone clicks a link on Writer River and arrives at your site, the post is displayed in a similar manner to the way it looks on the reading list. In my case this means it gets displayed without the title. And (another Tom Johnson tip) you can also put a note at the top of the page to explain that this is one item from a whole reading list of other links, and include a prominent link to that list (i.e. to your “What I’m Reading” category).
          
  To create a single-post template for a specific category, first add the following to your functions.php file, anywhere between the opening and closing PHP tags:
        
  

  add_filter('single_template', create_function('$t', 'foreach( (array) get_the_category() as $cat ) {     
          if ( file_exists(TEMPLATEPATH . "/single-{$cat->term_id}.php") )    
          return TEMPLATEPATH . "/single-{$cat->term_id}.php";     
  }    
  return $t;' ));

  (Source: http://www.nathanrice.net/blog/wordpress-single-post-templates/.)

  Now you can create a post template by creating a PHP file in your theme’s directory called single-n.php where n is the number of your “What I’m Reading” category. For example, the /itauthor.com/wp-content/themes/blueprint directory on my server now contains the templates: category-34.php and single-34.php.
        
  Once you’ve created these template files, you can edit them from the Edit Themes page of your WordPress admin pages. 
  
• Modify the Press This bookmarklet for your blog
        
  The Press This bookmarklet is a browser bookmark with added functionality provided by some nifty JavaScript. It makes it very easy to create a post relating to a web page you’re currently looking at – so it’s perfect for adding items to your reading list. 
         
  
         
  You get a Press This bookmark by going to the Tools page for your WordPress blog and dragging the Press This link into your bookmarks list.
        
  Note: The bookmarklet uses the inbuilt post editor for WordPress, so if you’ve installed a plugin that swaps the normal post editing buttons for something funkier (e.g. I was using Dean's FCKEditor For WordPress) you’ll have to disable this plugin or you’ll just get a blank text box in the little Press This window. I also had to disable the Disable wpautop plugin, which disables WordPress’s irritating automatic paragraph formatting, because with this enabled any line breaks in the Press This editor disappeared when I published the post.
        
  For me, posting to my reading list is the only thing I use my Press This bookmarklet for, so I want my “What I’m Reading” category to be selected by default.
         
   
        
  
  To add a default category (i.e. already checked) at the top of the Categories list in the Press This window, you need to edit the wp-admin/press-this.php file. Unfortunately you’re going to have to redo this change every time you upgrade WordPress. The stuff you need to add is in red. Change the category number and name as appropriate for your blog.
        
  

  <div id="categorydiv" class="stuffbox">     
    <h2><?php _e('Categories') ?></h2>   
    <div class="inside">     
       
      <div id="categories-all" class="ui-tabs-panel">    
        <ul id="categorychecklist" class="list:category categorychecklist form-no-clear">   
          <!-- Edit this line to suit your setup - my default category number is "34" and its name is "What I'm   
  Reading" –>   
          <li id='category-34'><label class="selectit"><input value="34" type="checkbox" checked    
  name="post_category[]" id="in-category-34"/>What I'm Reading</label></li>     
          <?php wp_category_checklist($post->ID, false, false, $popular_ids) ?>      
        </ul>      
      </div>     

  Kudos to johnke at the WordPress.org forums for suggesting this (http://wordpress.org/support/topic/216525).
• Create a twitterfeed for your reading list.
         
  Twitterfeed is an online resource that allows you to push the contents of an RSS feed (like a feed from a blog) into your twitter account, so that your blog posts (or the first few words plus an abbreviated URL) get sent out to your twitter followers. If you also syndicate your tweets to Facebook it means that your new reading list items will also show up as Facebook status messages.
         
  You can set Twitterfeed to check the RSS feed for your reading list once an hour. You can use the Advanced settings to add a prefix to these posts (I use “I've been reading: “), and I’d recommend setting it to include the “title only” rather than “title & description” because once you’ve added the prefix and the link to your post there isn’t much room for any more than two or three words from your post content.
         
   

Respect

I’ve already mentioned him a few times and, at the risk of embarrassing him, I must doff my cap once again to Tom Johnson who created Writer River and came up with most of the ideas I’ve fleshed out in this post.

Want to find out more? Go read these posts on Tom’s blog:

• "What I'm Reading": A New Feature on My Site and a Tweak of Writer River
• I Need Your Human Aggregated Content

Create a twitterfeed for your reading list.
       
Twitterfeed is an online resource that allows you to push the contents of an RSS feed (like a feed from a blog) into your twitter account, so that your blog posts (or the first few words plus an abbreviated URL) get sent out to your twitter followers. If you also syndicate your tweets to Facebook it means that your new reading list items will also show up as Facebook status messages.
       
You can set Twitterfeed to check the RSS feed for your reading list once an hour. You can use the Advanced settings to add a prefix to these posts (I use “I've been reading: “), and I’d recommend setting it to include the “title only” rather than “title & description” because once you’ve added the prefix and the link to your post there isn’t much room for any more than two or three words from your post content.
       
 

Respect

I’ve already mentioned him a few times and, at the risk of embarrassing him, I must doff my cap once again to Tom Johnson who created Writer River and came up with most of the ideas I’ve fleshed out in this post.

Want to find out more? Go read these posts on Tom’s blog:

• "What I'm Reading": A New Feature on My Site and a Tweak of Writer River
• I Need Your Human Aggregated Content

I’ve been doing a few little tweaks to my web site recently. Nothing major, just trying to make it easier for people to find stuff that might be interesting, either tucked away in one of my posts from the past six years, or on someone else’s blog. So, today I added a page listing a truncated summary from the latest post on the blogs I like to read:

http://www.itauthor.com/articles/recently-posted-by-other-bloggers/

I realise this kind of entices people to leave my site, but so what? It’s kind of dumb to expect people to hang around your web site for very long. For example, I regularly go to the BBC web site. I never stay there very long. I don’t browse through lots of pages. I’ll look at two or three pages and then I’m off somewhere else. But because it’s well designed and has good content I go back again.

But I’ve been thinking about my web site and how I’ve pretty much just blindly gone along with the standard WordPress format, with a panel down one side with links to category and month archives. I sometimes click a month link – typically back a month or two but rarely further. But I never click a category link and I suspect nobody else does either. I don’t use tagging, but if I did I think it would be the same thing. Why would anyone browse through a tag or category archive?

The navigation that I think is useful is the collection of potentially similar posts at the end of each post. Sometimes this throws up something that I’d forgotten I wrote about and I’ll click to have a look. I think other people reading my posts might also click to have a look at an older “similar” post if it sounds interesting.

So I think I’m going to take the category links out of the side bar. I’ll probably leave the calendar links in there for now, but I’m tempted to get rid of that side bar altogether and go for a really minimalist look. On the other hand I was also thinking that the site looks quite austere. So I’m also a little tempted to try and make it look less utilitarian.

But I’d be interested to know if anyone finds tag/category lists useful on a blog. Aside from never using them on my own blog, I can’t remember ever having used them when I’m reading other people’s blogs either.

Blogs used to be called Web logs, which was a straightforward description of what they were: sequential, time-based personal jottings, where you just kept adding entry after entry in a linear fashion. Now, what does that remind you of? A diary, right?

But these days blogs have long since evolved away from something that most closely resembled an online diary, into something that’s more like a multifunctional Web site. Nevertheless, blogs still make brilliant diaries. The trouble is, of course, that by default everyone gets to see what you write in your blog. One way round this is to download WordPress and install it locally on a PC, so that only someone logged onto that machine can access it. But that involves using something like XAMPP to install Apache Web server and MySQL.

A much easier way is just to sign up for a free blog at wordpress.com and then make particular posts, or the whole thing, private – as described in this WordPress video:

A couple of years ago, when this site was getting far higher Google rankings than it does now, and much more traffic (oh, the good old days!), I got hit by a tidal wave of comment spam that required a lengthy and tedious clean-up process to get it all out of my archives.

This happened while I had the WordPress Akismet plugin turned on. Akismet certainly picks up most comment spam, but a lot still gets through. After I turned on moderation I then had to do a weekly cleanup of all the spam sitting waiting for approval.

But since installing the WP-SpamFree plugin about six months ago, I’ve had no comment spam at all. None. Not one little bit of it.

So now, but with a certain amount of hesitation, I’m turning off moderation again. This means that anything you comment here, or on any other post, will be immediately visible to anyone who visits the site.

So go on. Give it a go. Leave me a comment. Go on!

Awh, go on, go on, go on, go on!

My last post included some code snippets.

I’ve never found an altogether satisfactory way to include nicely formatted and syntax highlighted code in WordPress. I’ve tried various methods but always ended up settling on something so-so after spending a while on it and eventually deciding I was wasting my time.

But this time round I tried again and found Chris Cagle’s Definitive Guide on WordPress Syntax Highligher Plugins.

In the spirit of “if  it’s good enough for him, it’s good enough for me” I decided to use the same plugin Chris settled on: Chili. You can see the results for yourself. However, although I’m fairly pleased with the end product, the process for getting there (using Live Writer) isn’t ideal. I’m documenting it here because, fortunately, I don’t often use code snippets, so this will serve to remind me how I did it:

1. Copy the code you want to use.
2. Paste it into Postable (an online processor for making code browser friendly):
   http://www.elliotswan.com/postable/
3. Click make it friendly.
4. Copy the browser-friendly code.
5. In Live Writer, go to Source view.

6. Create nested elements as follows:

   <p><pre><code class="html"></code></pre></p>

7. Change "html" for "php" or "c#" or "mysql" or "javascript" or "css". There are a few other supported languages listed on the Chili site. 

8. Paste the code into the middle, between the code tags. For example:

   <p><pre>
     <code class="html">&lt;p&gt;&lt;pre&gt;&lt;code class=&quot;html&quot;&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/p&gt;</code>
   </pre></p>

9. Publish your post.