Your README Is Important

Good documentation is very important and expected of open-source projects.

We should hold our private projects to the same standard. The README is not a @todo. It should be available and up to date, even if only for our own benefit.

But why?

It might sound like a waste of time to document something you’ve made for yourself but you’d be mistaken.

The faintest ink is more powerful than the strongest memory.

I’ve lost count of the number of times I’ve picked up an old client’s project and been thankful I’d included a I’d taken the 5 minutes to document the setup steps, and can now onboard myself even several years later. Instead of trying to remember my workflow of years gone by, the instructions are right there.

What seems obvious now, may not be later.

Practice makes perfect

Writing concise documentation is a worthwhile skill and you should practice whenever possible. Using the documentation on your personal projects is the perfect opportunity.

This practice will benefit you and others when documenting public or team projects.

Good documentation can be the difference between a project succeeding or not. Personally, I’ll skip any project that does not have clear and concise documentation.

Hone your documentation skills and give personal projects their best chance to succeed.

Where to start?

Dig into your projects folder, find a project that is missing a and get to work. Your future-self will thank you.

For tips on writing your README, refer to Eric Barnes’ great article on how to write a README that rocks.

Symphony CMS nginx rewrite rules

If you’re looking to use Symphony CMS on your nginx powered web server then the default Apache .htaccess rewrites will need to translated to nginx’s syntax.

I recently wrote about Symphony CMS and have since had a few people asking about the specific nginx rewrite rules I use, so I thought I’d share them here.

My rules are taken from Nick Dunn’s Gist posting I found on the Symphony forums, so all credit goes to Nick and the guys over there.

These rules need to be included in your nginx config file often found in /etc/nginx/sites-available/, and you’ll need to adjust ‘’ to your URL and the server root settings as appropriate.

Continue reading

Symphony CMS

Following up on the new tools and techniques I’ve picked up recently while putting my portfolio and blog live such as moving my hosting to Linode VPS and exploring alternative CMS systems, I’d like to introduce Symphony CMS.

Symphony CMS Logo

Symphony CMS, as the name suggests, is an XLST powered open-source content management system that goes beyond allowing you to create and manage websites, but complete web applications.

You could create a simple blog such as this to a bustling community website. You could even use it to power the data of an iOS app, or Flash website (if you’re that way inclined).

As you might have guessed, this website is built upon Symphony, however this is a relatively basic implementation of what it is capable of.

You can see more examples on the showcase, but I’d hastily remind you that you’re only limited by your own skills (design and coding) when it comes to developing with Symphony.

What is Symphony CMS?

Symphony is a CMS much like WordPress and ExpressionEngine, but it wouldn’t be foolish to see similarities to frameworks such as Ruby on Rails and CakePHP.

There’s not many projects I could think of that Symphony wouldn’t be suitable for.

Symphony is open-source

Symphony CMS Download Links

Symphony is open-source. It is freely available for you to download, and anything you build is entirely yours to distribute, sell or hide away as you see fit.

You could create a ‘white label’ CMS for your agency built upon Symphony, tailored to your exact needs ready to use on client websites.


Being open-source also means that there is a large community drive in improving the software from core fixes and updates, to extending the software through Symphony extensions.

If it’s not essential, it’s an extension. This keeps the system small, lean, and precise. Swiss Army knives are nice, but a surgeon wouldn’t operate with one. With Symphony, you craft exactly the tool you need.

‘Out of the box’ Symphony comes with just some basic features. The Symphony team take the view of ‘if it’s not essential, it’s an extension’. This is a real strength in my opinion, and is something thats been driving me away from WordPress.

This means that if you need a WYSIWYG Editor, its an extension. If you prefer to use Markdown, thats an extension too. Neither? Don’t install any, keeping your website as agile as possible and not burdened by features you don’t need.

XSLT and XML driven

Symphony driven websites are built upon XLST and XML, an open-standard templating language developed by the W3C that includes everything you need such as conditionals, parameters and functions.

XSLT (Extensible Stylesheet Language Transformations) is a declarative, XML-based language used for the transformation of XML documents.

This is great news as you needn’t learn even more custom template tags from a new CMS, instead you learn a transferrable skill in XSLT.

Using XSLT you can output your XML content to any format you wish, be it standard (x)HTML, HTML5, RSS/Atom feeds to PDF documents and SVG spreadsheets. Symphony is capable of driving the content behind near limitless types of formats and applications.

There’s a wealth of information regarding XSLT, but I’d recommend Symphony’s Tutorials or Stephen Bau’s DesignProjectX

Symphony CMS Features

No assumptions

Symphony is built on ‘Open Architecture‘ and doesn’t dictate what kind of content it’ll manage.

Symphony doesn’t tell you what kind of content to manage, or how. It doesn’t lock you into a rigid structure or dictate some silly URL schema. It just gives you the tools and stays out of your way. Trust us, you’ll like it.

Symphony is not ‘page based’ like a lot of CMS’s you may be used to. It makes no assumptions about your content. It doesn’t insist on there being a title, nor does it expect to it to have it’s own ‘page’ or even appear on the ‘front’ of your website at all.

Symphony CMS Admin Interface Example

You’re free to model your content, building one input at a time, allowing you incredible control over your project. As Symphony says ‘create what you need, and only what you need.

Custom Fields

There are no custom fields when every field is custom.

Symphony provides some basic fields for you to work with:

  • Author
  • Checkbox
  • Date
  • File upload
  • Select Box
  • Select Box Link
  • Tag List
  • Textarea
  • Text Input

Don’t see what you need? There’s probably an extension for that.

With planning and experimentation, you can build bespoke content models with appropriate selection of field types to create a ‘sections’ such as ‘Blog Post’, ‘Recipe’, ‘Employee’, ‘Product’ etc.

Tailored Admin

Just as you tailor your content model through Sections and Field Types, you’re also able to tailor your admin interface, grouping sections such as ‘Post’ and ‘Categories’ into a ‘Navigation Group‘ of ‘Blog’.

In addition you can pick and choose what sections are actually visible to your authors. For example you may have a Section of ‘Threads’ and ‘Posts’ for a forum, but wish to hide this from your authors as all forum moderation is done in the ‘front-end’.

Symphony’s settings, Sections, Data Sources, Pages, Utilities and Events are all managed through the ‘Blueprint‘ menu in the Symphony Admin. This menu is only shown to authors with the permission of ‘Administrator’ so you can have peace of mind that an adventurous client won’t dismantle their website’s vitals.


Extensions work a little like WordPress plugins in that they ‘extend’ the core functionality. Extensions can take many forms such as additional field types, enhancements to the admin panel, XML sitemap integration and more.

Symphony CMS Extensions Website

Unlike WordPress plugins however they often solve a problem rather than add a feature. For instance, they would enable a way to embed <object>s into your content rather than target YouTube videos specifically.

This allows you retain fine control over your project’s development rather than relying on an extension developer. It’s left to you exactly how a new feature is implemented.

Aggregate XML

As Symphony uses XSLT, and XSLT uses XML, you’re able to aggregate feeds and content from other sources with ease.

A classic example of this would be displaying your latest Tweets from an XML response.

You could tie this external XML to a data source in Symphony, and output it in just the same way you would any of your content. No plugins or mess required.

Debugging console

Symphony comes with a useful debugging utility available by adding ?debug to the end of your ‘front-end’ URL.

Symphony CMS Debug Console

Using this screen you’re able to see exactly what XML is being output to your pages based on your custom set of rules (date, URL parameters etc).

You can also see other useful information such as performance, allowing you to fine-tune your datasources and make sure they’re not firing needlessly and wasting resources.


Not necessarily a feature of Symphony, but by default your textarea fields can format content using Markdown. I’ve found this feature useful combined with Mou (OSX), MarkdownPad (Win) and Writing Kit (iPad).

I’m able to write freely without worrying about misplaced and invalid HTML markup such as rogue spans and open tags.

Using Symphony CMS

The Symphony CMS Tutorials are a great starting point to get up and running. Once completed, you can use the Concepts and API sections as a regular reference point while developing.

Stephen Bau’s Symphony-related XSLT tutorials have also been incredibly useful.

Symphony’s Community

As you’re working with open software there are many people around if you get stuck. The community forums are relatively small compared to say WordPress, but the members are very active, helpful and skilled.

Symphony CMS Forums

GitHub Development

If you’re a GitHub user you’ll be happy to know that Symphony is actively developed on a GitHub repository, while community extensions being encouraged to be developed as submodules.

This means you can very quickly ‘fork’ your own copy of the software and begin developing your latest project.

You can also then merge your local repositary, automatically staying up to date with all developments and ensuring you’re running the latest version.

Not into GitHub? You can download the zip package.

A marathon, not a sprint

As I mentioned, this website is running Symphony. It’s a simple blog / portfolio with an about me page.

I could have created this website quite comfortably with WordPress, and probably much quicker due to my familiarity with WordPress and the nature of this website’s content.

However, I’m glad I didn’t. Besides the fact that this has been a great learning exercise, if I’d decided to resist change and use WordPress I would have had to make a number of compromises.

The markup for this website site is all my own doing, good or bad, its mine. I’ve been able to tailor it exactly to my needs. I haven’t had to remove unneeded features as they were never there to begin with, everything has been built from the ground up with a purpose.

I’ve been able to build myself a platform, something truly customised, with the ability to expand on it in the future. If I decide I want a custom ‘client login’ section to my portfolio, handled by the same CMS as my blog, I can do that quite easily.

Try Symphony CMS

You should give it a go. Visit the official Symphony CMS website for much more (better written) information.

If you try it, let me know how it goes. If you get stuck, take a look at the Symphony CMS forums as I’ve yet to have a problem that they haven’t covered and solved.

Replacing WordPress

Following up on the new tools and techniques I’ve picked up recently while putting my portfolio and blog live such as moving my hosting to Linode VPS, I’m just writing to outline my decision to stop using WordPress as my ‘go to’ CMS.

WordPress logo

I’ve been using WordPress almost exclusively for client brochure websites for nearly 3 years, and will continue to do so as its a great piece of software, but I’m now learning it’s not always the right tool for the job.

This website was recently built using Symphony CMS. I could have quite easily used WordPress, in fact it probably would had been much faster, but I wouldn’t have had as much freedom to really tailor everything how I wanted it, and I really do mean everything. It’s also been a nice learning activity, but that’s all for another post.

WordPress Pros

WordPress is a fantastic CMS there’s no doubt about it, and if figures are to be believed it now powers 22% of websites in the US.

Quick setup

Getting a WordPress website up and running, with a custom design and a few additional features is very fast. This is partly down to my own familiarity with the software, but mostly due to WordPress being very feature rich ‘out the box’.

For example, I recently set up a client’s blog, based on their current websites design in about an hour using a freely available WordPress starter theme.

Pretty admin

WordPress Admin UI

I’ve developed many client websites with WordPress, and never really had a problem with the client not understanding the admin panel. Sure, there is an initial learning curve, but this is often very small.

I also do a lot of e-commerce work using Prestashop, and find client’s have more problems with the Prestashop admin panel, than they do with WordPress’.

Large plugin / theme repository

WordPress plugins directory

If you’re not too bothered about your website design being unique premium theme sellers such as Orman Clark do great work selling great looking themes on websites such as Theme Forest. You really could have a great looking website online in a morning.

There is also a mass of plugins available to enhance your website from great authors such as Yoast and Elliot Condon, who create two of my favourite plugins, WordPress SEO and Advanced Custom Fields.

WordPress cons

WordPress makes a lot of assumptions about what you would like to do. This is prevalent throughout creating a WordPress website.

While this is one of the huge reasons WordPress websites can be deployed so quickly, it can soon become a hinderance if you need something even slightly more bespoke. I’m not talking a Ruby on Rales or PHP framework app here.


WordPress Add New Page Button

WordPress is a ‘page-based’ CMS, and if the content goes beyond a simple Title+Content structure things start to get a little messy.

Yes, with custom fields you can do some pretty neat things, eventually, but ultimately you’re bending WordPress to near breaking point and it’s never felt intuitive to me.

I recently built a car importer’s website in WordPress, which including their car listings categorised by manufacturer, pricing, image galleries etc. It was doable, but wasn’t a whole lot of fun working with WordPress custom fields and could have been much better.


The admin is pretty and intuitive, thats in the ‘pro’ column, but a lot of it is often needless.

If I have a brochure website that doesn’t include a blog, the ‘Posts’, ‘Comments’ and ‘Links’ menus then all become a little redundant.

I can hide them in the functions.php or using a plugin, but its this sort of thing that makes me starting thinking ‘is this the right tool for the job?’.

There’s more examples of this, such as editors being able to change themes, and it all means I spend a decent chunk of development time bending the WordPress defaults rather than improving or optimising the project.


WordPress adds a whole bunch of functions into your <head>, often the first thing I do is remove them all in the functions.php using one of the many reusable WordPress function snippets I have saved.

Windows Live Writer shouldn’t be made available by default in my opinion, and should instead be an optional plugin. Its this sort of thinking Symphony does very well.

WordPress projects in the future

PrestaShop header tabs design

I run a modest Prestashop tutorial and news website, and while WordPress has been superb controlling the news/posts side of things, I’ve hit a brick wall when trying to tie in a Wiki and Community portion to the website.

I’d rather not use BuddyPress, or continually worry about bridging something like Vanilla Forums.

There are Wiki plugins available, but then you’re tied to what the plugin developer defines as a Wiki, and what features it should include.

It has quickly become apparent that WordPress isn’t the horse for this particular course, and I am underway redesigning/redeveloping the website using Symphony CMS.

A decision

As I say, I am not dropping my use of WordPress, and much like how I recently started designing in Fireworks rather than Photoshop, merely recognising when it is and isn’t the right tool for the job.

I’ll be using WordPress exclusively for quick brochure websites, and client’s who specifically ask for WordPress as their CMS (unless its definitely the wrong option!), but for more bespoke jobs I’ll turn to Symphony CMS, or finally get round to learning some damned Ruby on Rails.


I recently put my portfolio live and along the way embraced a lot of change and new tools and one of these changes was my recent decision to move my hosting from MediaTemple to Linode. (that’s my referral, please consider using it if this post is useful to you!)

Linode, if you’ve not heard, offer VPS hosting at varying levels, from 512mb to a staggering 20gb RAM. I won’t go into too much detail as you can find out more on their Features and Why Linode? pages.

Why move?

I’ve been a MediaTemple customer for a couple of years, they’re a great service and I personally found the customer support helpful and very quick to respond (via Twitter at least).

It’s pretty obvious they have a great brand. I’d seen developers proudly proclaiming their website was hosted by MediaTemple in footer. It was like designer label hosting.

I soon outgrew my previous host, Krystal, and their basic packages and at the time couldn’t offer anything quite like the bells and whistles of MediaTemple.

Its come to a point however where I was again re-evaluating my hosting needs. Rather than outgrowing MediaTemple, I felt I didn’t need the handholding and wanted something a bit more surgical than swiss-army.

Reviews and recommendations

Late last year I’d read a post on Linode by Matt Gemmell. His post was from a few years ago so I asked Matt over Twitter if he’d still recommend Linode, he would.

I googled around a little to find popular opinion for Linode‘s service, and it was a universal thumbs up from seemingly everyone.

This was a good sign as even with MediaTemple, a host I had been very happy with, for every good review there was also someone keen to share their displeasure with downtime or poor customer service.


Linode’s basic 512mb VPS comes in at $19.95/mo. This to me is an absolute bargain.

I currently have (dv) hosting at $50/mo and (gs) at $20/mo with MediaTemple, and while these are not the same services, the equivalent (ve) service is $30/mo.

You get nearly double the bandwidth with the (ve) (350gb vs 200gb), but with Linode this is an optional extra , so you only pay if you require it.

London, UK data centre

Over the last year or so I’ve become quite obsessed with page speed. Its good for your users, and its good for Google.

Linode allow you to choose from 6 different data centres, and the option to test the speed of each centre with a basic download trial. Naturally, I chose London

I try to pay attention to best practices regarding Page Speed in my websites, GZipping, CSS sprites, combined and minified scripts, optimised images etc, but the response time from the US data centres on my MediaTemple websites always felt like a let down.

VPS Freedom

I realise MediaTemple offer the (ve) service, but due to the 3 points above this wasn’t really an option.

I loathe Plesk, it feels like unnecessary bloat and made tasks more difficult as you were wrestling with the software, bending it to do what you actually wanted.

I felt I’d outgrown the control panels and pre-written software of the (dv) server, and the shared hosting of (gs). Although in fairness MediaTemple’s control panel is excellent.

Too much to mention

I could go over everything but instead I’d recommend you take a close look at Linode’s features

My Linode setup

I opted for the basic 512mb VPS to begin with as Linode make it very easy to upgrade via your Dashboard as your requirements change.

Following the straight forward Getting started and Set up a LEMP Server on Ubuntu 10.04 guides in the Linode Library I was quickly up and running.

My setup is as follows:

Ubuntu 10.04

Being new to all this I chose to use the widely recommended Ubuntu 10.04 as my OS, which was as easy as selecting it from a drop down menu in Linode’s dashboard.

I have no preference to any particular Linux distro, I know very little about the differences, but Linode offer many different flavours in many different versions and your server is ready to use almost instantly after selection.


Nginx is a lightweight web server. I’d had memory problems using Apache in the past, even having just a handful of visitors on a site at any one time and my web server would become cumbersome.

I’d done various optimisations but things still weren’t ideal, and I couldn’t justify the large jump in price to a more hefty (dv).

“Apache is like Microsoft Word, it has a million options but you only need six. Nginx does those six things, and it does five of them 50 times faster than Apache.”
Chris Lea

As Chris describes, I’ve found this to be the case. The memory footprint is much lower with the same traffic, and I’ve been able to do everything in Nginx that’d previously needed from Apache.

I’ve had to make a few modifications to the Symphony CMS rewrite rules, translating them from Apache to Nginx, but this was the only change that was needed. As a personal side note, I’ve also found the Nginx configuration to be much more intuitive.

As my Linode server is only 512mb, Nginx seemed a logical choice.


Obvious choice really. I’d like to look into areas such as MongoDB in the future, but as a lot of my work uses open-source CMS systems and frameworks supporting MySQL only, I’ll stick with what I know.


PHP-FPM is a FastCGI implementation of PHP that cleverly adapts its processes based on traffic load. You can find out more on their website, and there’s various guides around for installing this as a package.

E-mail hosted by Google Apps

This was a bit of a no-brainer, and I’ve been meaning to do it for a while now.

Rather than hosting your own memory hungry mail server, spam filter, IMAP processes etc, Google will do this for you for free.

They allow you to have up to 10 e-mail accounts, all integrated with Google calendars and Google docs. You can Sync your contacts too, making them accessible from all your devices.

Connect to your e-mail using traditional POP3/IMAP clients such as Apple Mail/Outlook/Thunderbird, or use the webmail service (the slick Gmail interface). You can even setup a custom domain such as

Simply point your MX records in your DNS to their servers and they’ll take care of everything. All for free, I honestly can’t see many reasons why you wouldn’t want to do this.

Try Linode

In summary, I’m only a few days in and I’d highly recommend trying Linode. Setup was quick, migration was painless, and my website appears to be stupidly fast.

Google Plus +1

Google Plus +1 Buttons

Google this week have released their long talk about +1 button and much like the prominent Tweet This and Facebook Like buttons you will see all over the web. +1 buttons let people who love your content recommend it on Google.

Continue reading