desk or wall - dark

Finally happy with the creation of a web site

In the past, I never managed to build a web site and feel happy with the process. Every time I finished building a web site I would have a list of things to never do again. Until now! So, I thought I’d share.

First, by web site I mean content, like or, I don’t mean a web app. I’m happy with how I build web apps although I’m constantly improving and learning and trying new things. When it comes to content, you have to balance some opposing forces:

  • It should look amazing.
  • It should be flexible.

It should look amazing because it’s going to be compared to the ones produced by expert teams of designers at tech companies and if your web site is not indistinguishable from those, your web site will be perceived as unprofessional and as a result, so will you and your product.

I had web sites that looked very good. A graphic designed was hired to produce a pretty illustration of the web site and then a coder turned that picture into HTML and CSS. New pages were created by hand-coding them in HTML. The process of setting up the web site initially was ok, but after that, the workflow was horrendous.

Changes to the web site would come from non-coders, like the CEO, people in marketing or sales, copywriters, and they would be given to a developer to execute. Then we would have to prioritize between improving our web site or improving our product. Almost always product wins… only when the web site got the point of being embarrassingly out-of-date or broken we would consider doing something about it. This situation is annoying and frustrating for both developers and content generators.

The way to solve it is with a Content Management System, where things get flexible. With a CMS suddenly anyone with a browser and the right access can edit the site, add new pages, correct typos, add a FAQ, change a title, write a new blog post, etc. It’s as easy as Microsoft Word and the output is as generic, boring and bland as that of your average Word document. It might be ok for text files, but on the web, that screams unprofessional.

The problem is a tricky one. You might think there’s a nice separation between design and content but that isn’t true. A content writer might decide to have only one column of text instead of two because there’s not enough copy. But the difference between one and two columns is a big one when it comes to design. The content might call for a picture or even worst, a drawing. The design establishes the palette and style of that drawing.

A screenshot of Screensaver Ninja's web site

A screenshot of Screensaver Ninja’s web site at the time of this writing.

I just finished rebuilding the web site for Screensaver Ninja and for the first time I’m happy with the result. Not only how it looks, but the amount of work and funds require as well as the flexibility and workflow going forward.

The CMS we are using is WordPress and we host it at wpengine, which I really recommend. Not the cheapest, but if you care about your web site and you can afford it, you should go there.

One potential approach to having a beautiful site would be to go to 99designs and run a contest for a WordPress theme. My hesitation is around the flexibility of the result. Will the new design be completely hard-coded or will I be able to change the copy? What about changing more involved aspects like the amount of columns or images. I’m not sure and asking around did not reach any useful answers. If you have taken this approach, would you mind sharing how it works with me?

The approach we took was to use a very flexible and advance WordPress theme called X. We chose one of their many templates for a page that we felt would match our current branding and the message we wanted to communicate. We proceeded to fill it up with our own copy following this tenets:

  • Change as little as possible.
  • Ignore all images, just leave them blank.

Once copy was done, we hired a designer through a freelancing marketplace and ask her to produce images to fill in the blanks. We showed her our web site with the blank images as well as the original template with sample images and asked her to keep the style and palette. We provided some ideas for the images and she came up with some as well. After a couple of iterations we had all the needed images.

And that’s it. That’s how we produced that site. Yes, it’s possible that out there there are other sites that look exactly the same, but it’s not a big issue. It’s like worrying that somewhere out there there’s someone with the same t-shirt as you. The chances of you two being seen by the same person in a short period of time is small and even if that happens, whether the t-shirts fits you or not is more important. Nobody will care about your originality of clothing if they look horrible and the same goes for your web site.

Next time i have to build a web site for a product, I’ll do this exercise again and I recommend it to all entrepreneurs that are working in a small company and need to be efficient.

Uptime: 100%

Balance by Tony Roberts

This is the first time I see this:

Outages: 0
Downtime: 0 hrs, 0 mins
Uptime: 100.00%

It was always above 98%, often above 99% and I was proud of that because it was my own crappy server doing it. But now I’m proud of not caring about it, letting someone else solve a problem I’m not interested in and focus on what I am interested in. 100% uptime provided by

A little personal success

This page, my blog,, is now hosted on instead of my own server; and that’s is a little personal success. Let me explain.

I tend to be a control freak. I have my own servers. I run my own nameservers. I used to run my own mailserver but some time ago I switched to Google Apps for Domain. I used to run my blog in my own server, keeping my own set of plug ins, even modifying themes when necessary.

Last weekend I published Why I love Smalltalk and it got picked by Hacker News. That traffic killed my server. I spent the whole weekend restarting and tuning Apache. You see, I can run my own server, use Puppet, keep it clean and up to date but I’m not a sysadmin. I can pretend I am for short periods of time but I’m really just a coder. I was forced to have a crush course into server tuning and I eventually got it more or less stable. By the second wave of traffic it was not trashing anymore. I have better things to do with my time that tune a web server so I decided to move and I did it.

It is a personal success because I’m giving you up control. I can’t install whatever plug in I want now. I can’t modify themes. I’m not using my own nameservers anymore. I’m giving up control and simplifying my life when I have a natural tendency to make it more complex than it is.

At the moment, my beloved is not ny any of my servers. Nothing. Every service related to is running on third party hosted solutions. I’m letting go, sleeping better and being happier.

Only a couple of hours after I migrated my blog and went it sleep it was picked by Reddit. More than double the traffic of Hacker News (that is, Hacker News minus my server downtime) and I didn’t woke to a burning and smoking server, just an impressive traffic chart and even more comments. I’m happy.

Reviewers in a WordPress blog

In an effort to increase the quality of this blog I’ve engaged a couple of friends in reviewing my posts before they go out. I’m after typos, grammar and also “Are you serious? are you going to publish that crap?” or “You are going to get into trouble with that”.

The best way to do this, in my and in the opinion of many, is to let the reviewer modify the post freely and then check the diff. I suppose we are too used to work with source code, where diffs are a necessity.

I was positively surprised that WordPress can provide very nice colored diffs between each save of each post. Praise to WordPress! I was also surprised, but negatively, that WordPress doesn’t have a reviewer role. Users with the reviewer role would be able to edit unpublished posts but wouldn’t be able to modify published posts or publish drafts.

I was pointed to Role Scope, an amazing plug in for WordPress. I spent an hour creating a group and trying to give it the proper access, and as that failed, trying to limit the Editor role to only edit drafts. I failed at that too.

When I gave up and I went back to the usual blogging I found that Role Scoper allows you to give edit access to each post to any user. And that’s it. That’s what I’m using. Whenever I want something reviewed I give access only to that post to the user I want to review it. Quite simple.

Reviewed by Daniel Magliola. Thank you!

Increasing views without changing content

Wordpress, image taken from: days ago I’ve switched from Plone to WordPress, again. I want to take my blog and web site into a new direction so I wrote a bunch of  drafts. But something unexpected happened. It already got a new life and I only published one new post (which wasn’t very popular either).

Analytics says that in the last 7 days I was already 31% better than the previous 7 days. And I’ve been running WordPress for less than 6 days. Furthermore, I’ve had rather large downtimes, about 24hs, as I moved things around, installed plug ins and wrestled with Apache. So, all in all, the improvement was rather large.

My  hyphothesis is that WordPress presents the information in a much better way, both for humans and computers. For computers I mean that it’s more easily indexed, it pings other aggregators and who knows what else. You could say it’s very SEOed.

For people it’s easier to use and more familiar. People are used to looking at blogs that look like that. I  don’t think this is to say that WordPress is better than Plone, I still believe that Plone is the best CMS out there, but the skins and design and the way the information is presented in list and topics should be improved to be more like WordPress and/or Mediawiki.

The really important lesson is that when you are making your own web site, maybe your own product with your own functionality, the presentation should be something familiar to the users. A good example would be Hunch, which you could say it’s a carbon copy of FlickrExcept that it doesn’t have anything to do with pictures or images! They made an interface that looks familiar for most users, so they can learn what Hunch does without being scared right away.

Reviewed by Daniel Magliola. Thank you!

ReStructured Text on WordPress

I am coming from the Plone world. My web site used to be Plone and various website I still maintain are still Plone-based. In Plone, one of the formats to write text is ReStructured Text (RST); and Matt has convinced me it is the right way… or at least, one good way. But in the world of WordPress, RST is not a first class citizen.

Searching for “restructured text wordpress” I’ve found an article titled “Using reStructuredText with WordPress” . That seemed like good news. The author talks about a plug in, but getting it to work required some work on my side and that is what I am trying to show here.

Disclaimer: poorly written article ahead (and above), take the information, ignore the prose.

First, the plug in is not distributed as a compressed archive (tar.gz, tar.bz2, etc) like software is generally distributed but as a TXT. You have to download rest.php-1.2.txt to your plugins directory of your WordPress install and rename it to “rest.php”.

In the computer were WordPress is installed you should also have Docutils installed, particularly the program rst2html. The plug in has a hard-codded path to reach that program, around line 18:

// Set this to the prefix of your docutils installation.
$prefix = "/usr/local";

// Set this to the path of
$rst2html = "$prefix/bin/";

since I am running Debian GNU/Linux and installed Docutils using the package, the binary was in /usr/bin/ so I have to change the prefix to be:

// Set this to the prefix of your docutils installation.
$prefix = "/usr/local";

Also, due to various personal preferences, I’ve changed the line 116 to:

$execstr = $rst2html . ' --no-generator --no-source-link --rfc-references --no-doc-title --initial-header-level=2 --footnote-references="superscript"';

To know more about it, read the man page of rst2html.

The other important change is that around line 100, there’s some code to replace the “more” HTML links that WordPress insert with RST links. The problem with that is that the code searches for a particular text (“(more…)”):

$pattern = '\(more...\)';
$replacement = "\n\n`(more...) < \1>`__\n\n";
$text = ereg_replace($pattern, $replacement, $text);

but that text is skin-dependent, so I changed it for:

$pattern = '(.*)';
$replacement = "\n\n`\2 < \1>`__\n\n";
$text = ereg_replace($pattern, $replacement, $text);

which is more generic and will successfully correct all the links, no matter what they say. Now that I take a look at it, the line jumps in the RST version shouldn’t be there. This had an unfortunate consequent. The text of the a element of an HTML link can have HTML specific stuff, in my case it had one HTML entity. The right thing would be to expand all HTML entities into text, but I just did a search and replace for this particular one. An ugly hack indeed:

$pattern = '»';
$replacement = "»";
$text = ereg_replace($pattern, $replacement, $text);

And at last the jewel. If you don’t write -*- mode: rst -*- somewhere in the article, then it won’t be RST, it would be the built-in simple WordPress markup language whatever that is called. You can prefix that with two dots and a space, like “.. “, in the beginning of the line to also turn it into a RST comment so the actual text doesn’t appear in the final article.

You’ll see that there are many nasty things here, lots of hacks, etc. The right thing would have been to solve the bugs, make a customization page to set the path and the RST options and make the solution more generic. Then pack it and release it. I am not going to do that, enough time has been spent writting it down here, now I am back to my main project. This is related to what I’ve said in my previous post regarding worrying less about the perfectionism of my web site and work more in my personal projects.


Comments in the original post

  1. Matt Dorn Says:
    Finally caught up with your new site and updated my RSS feeds–looks nice! But I like that I can now read your entire articles within my RSS reader instead of just the introduction.I agree that Plone is not ideal for a personal site, though I think I’ll be keeping mine for a while. I would like to get comments activated without hosing my Apache caching setup–that seems to be the main challenge, because running a Plone site without caching is not advisable.

    Re. our shared enthuasiasm for Restructured Text, I just had another occasion to appreciate it. You can use it in Tracs. I also got Tracs working with Darcs, which I know you use as well. Have you thought about making your software projects available via Tracs projects? If so, the writeup I just did might help you:

    February 1st, 2007 at 13:01

  2. Pupeno Says:

    Hello Matt,

    Nice to see you active in the community. When I was re-structuring my web site I’ve decided to use Trac for my projects but after a quick try I gave up. A quick try to use it with Darcs (or nothing at all) that is.

    Now that you have written a tutorial about it I am going to read it and give it a nice try. Isn’t it nice that I helped you start with darcs and now you help me start with trac plus darcs? That’s karma!

    February 1st, 2007 at 20:40 e

  3. Ivan Says:

    Dear Pupeno,

    I’ve just installed this plugin to a blog on my local machine (not the blog above). It doesn’t quite work. If I could get it working it would be an absolute godsend. Please help.

    When I add the mode line to a post, wordpress then ignores the entire body of the post – I get the title and nothing else. Any idea what might be wrong?

    I have no knowledge of php at all, my main language is Python. Would it be possible to write plugins in Python?

    My blog is fairly new. I’m enjoying using wordpress, but the rest of the time I more or less live in emacs and use rest for most of my documentation. If I could write my blog posts in rest I should be very happy. Would be prepared to put some work into this to get it working.

    Best wishes


    June 15th, 2007 at 12:52 e

  4. Pupeno Says:
    Hello Ivan,Be sure that the plug in is activated. Otherwise, contact the plug in author.

    I am not sure about programming plug ins in Python but I doubt it’ll be possible, you should check in WordPress’ site and mailing lists.

    I am only a user of WordPress, my knowledge of its internals is null, but if you ask in WordPress’ mailing list or IRC channels, I am sure you’ll get a lot of help.

    June 16th, 2007 at 13:53 e

  5. you know something? » Blog Archive » Happy! ReST Says:
    […] 落ち着いて考えれば、すぐ分かりそうなものですが、 以前、うまくいかなかった理由は、 をあらかじめインストールしておいて、 rest.php 内のパス を書き換えておかったため。 […]September 7th, 2007 at 2:41 e
  6. ROTR » reStructuredText for WordPress is now a Launchpad project Says:
    […] Pupeno […]September 9th, 2007 at 5:30 e