Ken (legend)

Software development never changes

In the early ’80s, my father trained countless Cobol programmers. A mantra that he always repeated to every single one of his students was this:

A good programmer focuses on getting the code right, while a great programmer focuses on what the users have asked for.

That was over 30 years ago. Around the time BASIC was invented – before C++, Turbo Pascal or Perl even existed and long before PHP, Python, Ruby, Javascript or any language that we actually use today had even been conceptualised.

Jump ahead to 2015.

This week I was interviewed on the WisdmLabs blog about my WordPress development practices. They asked me: What is the difference between a good developer and a great developer?

The answer was fairly obvious to me, not because my father had told me (I never knew he even had that mantra), but because this is just the way I have always viewed things:

A good developer focuses on code, while a great developer focuses on users.

So what’s changed in 30 years of software development?

Nothing.

Sure, we have new technologies available to make things easier – simpler languages, more convenient libraries, new coding standards and more efficient IDEs. But none of that will ever change what the main focus of any software development should always be: users.

If users aren’t at the centre of your development then you’re already doing it wrong.


I should probably point out that the guy in the photo at the top is not my dad – that’s Ken Bowler, a systems programmer from the University of British Columbia circa 1980.

Seriously Simple Podcasting Docs

Building a simple & beautiful documentation site

With Seriously Simple Podcasting crossing 35,000 downloads and v1.8 of the plugin being released recently it was high time that I put together complete documentation for it. After spending some time building the site that you can now find on my new docs subdomain I thought it would be valuable to share the tools I used for posterity. So here you will find the theme and plugins that I used to get my docs site up and running.

Theme

As with any custom design I embark on, I used Canvas by WooThemes as my parent theme. I’m not much of a designer, so I find Canvas to be a great substitute for my lacking design skills. The design and typography options do wonders to make someone like me look like they know what they’re doing with design work.

For my typography I went with Ubuntu for the headings, Open Sans for the body text and Droid Sans Mono for the inline code.

Seriously Simple Podcasting Docs Homepage So, with Canvas as the parent theme, I built a custom child theme to cater for my needs. You can download that child theme from here if you like (it includes the theme settings export file), but it obviously contains a number of customisations that would be unique to my site. It also requires the plugins I used to make this site a reality.

Plugins

With the theme taken care of I could now look the plugins I needed.

Docu

To start off with I looked around for a decent documentation plugin and, having found nothing workable, I was about to start writing my own one when Emili Castells got in touch with me about his new plugin, Docu. Docu is a simple and flexible documentation plugin that doesn’t add any extra bloat or overhead to your site. It comes with a new custom post type and taxonomy for creating and categorising your docs as well as nicely designed templates (that you can override from your theme) to help you display your docs easily.

I added a small amount of custom styling and logic to the display, but other than that Docu effectively works very well right out the box.

Table of Contents Plus

A necessary feature for any docs site is a table of contents on each document. For me, the best table of contents plugin I’ve ever used is Table of Content Plus. It gives you a number of options for how to display your document contents, but all-in-all it’s a very easy plugin to use that requires only minor configuration to get working.

Screen Shot 2015-02-10 at 10.14.37

oEmbed Gist

As this is a documentation site that includes developer docs, it’s necessary to show code snippets from time to time. One of the best ways to do this is to store your snippets on GitHub’s Gist as it makes them public and easily discoverable. The next step is to embed them in your site content, which unfortunately WordPress doesn’t natively support. Enter oEmbed Gist – just install the plugin and pasting your Gist URL into your content will generate a neat oEmbed of the code.

Pro tip: I use GistBox to create and manage my Gists – it has a great UI and makes team collaboration much easier.

Relevanssi

WordPress’ built-in search has always been mediocre at best and there are a lot of plugins out there that are built to enhance the search experience in WordPress. My favourite of these plugin is Relevanssi – with a few simple options you can boost your site’s search effectiveness by leaps and bounds. This is incredibly important when working with documentation as the search is often the first port of call for many users.

An added bonus with Relevanssi is that it allows you to track your user’s searches so you can see what search terms are the most common.

Testimonials by WooThemes

There are loads of plugins available for adding testimonials to your site, but my favourite is definitely Testimonials by WooThemes – it’s especially useful if you’re using a WooThemes theme as it integrates smoothly with the design of your site. The content for the testimonials is all copied from the plugin reviews on the repo.

Screen Shot 2015-02-10 at 11.14.17

Acknowledge Me

The final plugin I used is the handy Acknowledge Me plugin by the guys behind the Pods Framework. Because Seriously Simple Podcasting is an open-source plugin that has had a couple of different contributors help to make it more awesome, I thought it would be good to acknowledge them on the docs site. Acknowledge Me displays all of the contributors to a GitHub project in a neat grid with avatars and contribution counts – all I needed to do was some minor CSS changes to have it fit into the design of my site more effectively.

Screen Shot 2015-02-10 at 10.17.41


And that’s all there is to it. All of those plugins are freely available from the WordPress plugin repo so getting all the functionality you need for a docs site won’t cost you a cent and, while the theme isn’t free, it’s well worth getting a Canvas licence for all of your custom design needs.

Instant Featured Image

Introducing: Instant Featured Image

While WordPress is, I believe, the perfect platform for pretty much any kind of online publishing, it does have some occasional UX inconveniences. The great thing is that, due to the extensible nature of the platform, most of these inconveniences can be fixed via plugins. Enter Instant Featured Image.

Like my Quick Empty Trash plugin, Instant Featured Image simply adds a single additional button to the WordPress UI, but it makes a significant difference to the post editing experience.

What is it?

Instant Featured Image boosts the WordPress UI by adding a new button alongside the ‘Insert into post’ button in the media manager modal. When clicked, this button will insert your selected media and then, if you have selected an image, set that image as the post’s featured image. It is possible to select multiple media items to insert, so this plugin will set the last image in the selected set as the featured image.

Who is it built for?

I originally built this plugin specifically for Remkus de Vries as he tweeted about a need for this exact solution:

I agreed that it would be a very useful addition to WordPress and went ahead with building it for him and anyone else who found a use for it.

Ultimately though, Instant Featured Image is useful for anyone who deals with images in their blog posts and almost always uses one of the content images as the featured image. In fact, it’s seen as something so useful that WP Tavern wrote about it shortly after I released it.

Why did I build it?

I built this plugin to help out someone who needed it, but I also saw a gap in the WordPress UI that really needed closing. The plugin was fun to build and, while it’s something I rarely have a need for myself, I’m glad I built it to help those who do have a strong need for something like this.

[wp-pic type=”plugin” slug=”instant-featured-image” align=”center” layout=”large”]

Post Length Indicator

Introducing: Post Length Indicator

Have you ever found a blog post, noticed that the scrollbar is super long and decided to abandon reading because you just don’t have the time to read that much? How many times have you actually scrolled down to see how long the actual post content is before you arrive at the comments? If you took a minute to check the post length you would more often than not discover that the scrollbar only appears so long because the post has a huge amount of comments.

Some people solve this issue by adding a ‘time to read’ line at the very top of the post, but I thought I would solve it a more visual and altogether unobtrusive fashion – which brings me to the aptly named Post Length Indicator.

What is it?

Post Length Indicator is based on an idea I read in a blog post a few years ago, but for the life of me I just cannot locate that post again.[1. If anyone else read the blog post and can remember it then please let me know!] The concept is simple – the plugin displays a visual indicator of how much of the page contains post content and how much contains the comments. It does this by displaying a dual-coloured bar alongside the scrollbar – the top section of the bar is the portion of the page that is made of the post content and the bottom section is the comments portion.

You can see the plugin in action if you look over at the scrollbar on this very post (or any other post on my site).

The colours of the bar are customisable via the settings, and you can also select on which post types the indicator should display.

Who is it built for?

Post Length Indicator is, quite naturally, designed for blogs that receive many comments on each post. It can be used on any WordPress site, but unless you receive a whole lot of comments then it becomes largely unnecessary. That being said, it is very unobtrusive and doesn’t really overpower the rest of your content, so there’s no harm on installing it on sites with low comment traffic.

Why did I build it?

While I use Post Length Indicator on my own site, I didn’t build it for my own use like I do for many of my other plugins. I originally built this plugin as a proof of concept more than anything else – I still had the idea from the original blog post I read about the idea and I wanted to make that a reality for WordPress.

Due to the incidental nature of the plugin it hasn’t received a huge amount of downloads, but that’s OK with me – I think it fleshes out a fun concept very nicely.

[wp-pic type=”plugin” slug=”post-length-indicator” align=”center” layout=”large”]

Export Plus

Introducing: Export Plus

The great thing about WordPress is that, as an open-source and community-built platform, anyone can contribute code to it. Whether it’s small fixes, or big new features, patches can be submitted by anyone and everyone. Once such patch that I submitted was an improvement to the existing export tool that is built into WordPress itself. Unfortunately, that patch has not been merged into core yet and I’m not sure when it’s going to be, so in the mean time I packaged it up as a plugin.

For lack of anything more creative, I named it Export Plus.

What is it?

The existing export tool allows you to select only one post type and, if it is anything other than the built-in types, you cannot filter what content you export. This is hugely limiting and can make exporting data incredibly frustrating. On top of that, the existing tool uses raw database queries instead of making use of the WP_Query class, which would be safer and more manageable.

Export Plus adds a new export tool to the WordPress dashboard that allows you to select as many post types as you like and filter them all across your desired date range as well as their author. You can also select which category to export for posts and I will be adding further taxonomy selection for all other post types in a future release.

Additionally, this plugin uses WP_Query instead of raw database queries.

Export Plus screenshot
A screenshot of the Export Plus UI

Who is it built for?

As with Quick Empty Trash, Export Plus is built for anyone to use and isn’t tied to a specific industry or type of site. The way I see it, this plugin offers such an improved export experience that there’s no reason it shouldn’t be included in core (but I’m obviously rather biased).

Why did I build it?

As with so many other plugins, I built this tool to make my own life easier. The current export tool in WordPress is exceptionally frustrating to use and I really wanted something that would be more flexible and more useful.

[wp-pic type=”plugin” slug=”export-plus” align=”center” layout=”large”]

banner-772x250

Introducing: Quick Empty Trash

WordPress plugins don’t always have to be huge new features that add loads of new functionality to your site – plugins that do one small thing are equally valuable and, if written well, can drastically enhance the usability of your website with almost no additional performance overhead.

Quick Empty Trash is one such plugin. All it does is add a single button to your WordPress dashboard, but it can still make a big difference to your workflow.

What is it?

Quick Empty Trash is a plugin that, as the name suggests, helps you empty your trash more quickly. The plugin adds an ‘Empty Trash’ button to the post list table for all your post types. Normally this button appears only when you’re viewing the list of trashed posts, but with this plugin the button appears on all statuses when there is at least one post in the trash for that post type.

The benefit this gives is that you no longer need to load the trashed posts in order to subsequently delete them all.

Who is it built for?

This plugin is built for anyone – it has no specific use case, other than speeding up your work flow when deleting posts.

Why did I build it?

At the time that I built Quick Empty Trash, my site’s dashboard was performing very badly (mostly due to the hosting I was using at the time) so loading up the trashed post list took ages. This plugin enabled me to empty my trash without waiting for that long extra page load. It may sound petty, but saving a few minutes each time you perform a fairly common task is incredibly useful.

[wp-pic type=”plugin” slug=”quick-empty-trash” align=”center” layout=”large”]

WordPress: Add items to the ‘At a glance’ widget

The WordPress dashboard includes a handy widget that displays some brief information about your site at a glance – rather creatively, it’s titled  ‘At a Glance’. By default it shows you the number of posts, pages and comments on your site allowing you to click through to edit each of those sections if you have the right permissions.

When building a plugin with a custom post type, it’s often a good idea to add your post type to the widget as it makes things more accessible and generally more user friendly for everyone. Using the snippet below you can add any number of custom post types to this widget (I’ve also included some useful CSS to customise the icons displayed):

All you need to do is replace the $post_types array with an array of the post types that you want to add to the widget. You’ll see that the snippet includes a security check so that only users with permission to edit each post type will be able to click through and do so.

The CSS will replace the circle with the same icon that the Posts post type uses. You can replace the content attribute there with one of the icons from this set – just select your icon and copy the relevant CSS from the link provided.

WordPress: Random post order with correct pagination

Randomising the order of the returned posts in a WordPress query is easy – simply add  'orderby' => 'rand' to the arguments and you’re good to go – this is great, until you need to paginate the results. As soon as you navigate to the second page of the results, the posts are returned randomly once again and you get an entirely different set of posts that may or may not contain posts that you have already viewed – if you’ve experienced this before then you’ll know exactly how frustrating it can be. After having this problem numerous times myself I decided to find a way around it.

The first thing we need to do is make sure our PHP session is initiated. You will see the reason for this in the function itself, which is where the magic happens – here we will use MySQL’s RAND() function and supply it with a seed value so it uses the same random order on every subsequent page load. To do this we will store a random string as a PHP session variable so it can be used by MySQL as a reference for the order to use for each page. All we need to do is add this snippet to our theme’s functions.php file:

You will notice one extra operation on line 7 of this snippet – we also reset the seed value every time the first page of the posts are loaded. This means that as long as someone stays on the paginated pages they will see a consistent set of results, but once they go back to the first page the randomisation will reset and they will see the posts in a completely different order.

Note that in this example I have limited the ordering to the front page only (that is, the home page of the site when the front page is set to show your latest posts), but you can change the conditional to target any page or post type archive that you like.

Simple animated scroll for jQuery

If you use links to navigate to other elements on the same page, it’s generally a good idea to animate the scrolling so you don’t disorientate your users. There are jQuery plugins (such as ScrollTo) that offer many different ways for handling this, but if you don’t want to mess about with all the features of a new plugin then this snippet will be very useful. It’s a simple function that will scroll your page to any DOM element that you specify:

As you can see you can also specify the speed and a top offset for the scroll (I find this top offset very useful as default behaviour puts the target element flush with the top of the browser, which can make things feel a bit cramped). An added bonus is that it appends the target string to the current URL, so if you are using a standard anchor reference (such as #element) then users will be able to grab the URL and it will point to the correct location on the page. If you are using other selectors to target an element then I would recommend removing the function inside the animate call.