Safe from the Losing Fight

At the risk of becoming part of something trendy (which my nerd contract expressly prohibits), I’ve finally ditched Wordpress in favor of static solution. Unlike everyone else though I’m not ditching it for performance reasons, because honestly, I don’t get enough traffic to bring down London bridge, which, according to a song I once heard is constantly falling down.

No, what prompted this change was my Wordpress install getting hacked for a third time (to inject spam links, of course). It’s not entirely Wordpress’s fault; each time my version was out of date, despite Wordpress making updating to the latest version super easy. Unfortunately I don’t go the Wordpress admin panel every day to check for updates, so I’m routinely out of date.

All of which to say, I needed something other than Wordpress to get around my update delinquency. Specifically here’s what I wanted:

• Little to no code running on the server, with a strong preference for none. No database, either.

• It should generate a static site, from flat text files.

• It should be able to import all my Wordpress entries

• Support the Wordpress site/link structure so that it wouldn’t break existing links into the site.

And a couple of nice to haves:

• Support some version of Wordpress themes, or at least make it easy to port them.

• Work with MarsEdit

In other words, I wanted Wordpress without the Wordpress.

There were a couple of solutions that got close, but none that did all that I wanted. So, being an engineer, I decided to write my own, which I codenamed Postword. I actually started the project back the last time I got hacked, and even used an early prototype for the blog on Hearts & Tactics.

Postword is more or less a collection of Ruby scripts. It has one to take a Wordpress XML file and convert it into a bunch of flat files (one for each post) that can be processed later by the build script. The flat files are nothing special; they have mail like headers for the categories and title, and then body which is just text with some HTML markup allowed. The build script takes these flat files and builds a full site that looks like Wordpress site structure wise. The script is unique in that it supports the idea of themes, whose API just happens to be the exact subset of Wordpress APIs that my custom Wordpress theme happens to use.

And that’s all Postword was up until a couple of days ago. But if was going to use Postword on this site, which I update somewhat frequently, I needed to reduce the friction. The first thing to do was to write a publish script that pushed the local static site to my server via FTP. I wrote my own script in Ruby, which actually turned out to be not that bad, since I could make a lot of assumptions. The important one was that the local site was always the truth. Which meant if the local and remote ever differed, the local overwrites the remote, and if the remote had a file which the local didn’t the remote gets deleted. In effect, the site becomes self-healing.

The last piece of the puzzle was create a local server that MarsEdit could talk to. MarsEdit supports a lot of different APIs, so I had to decide which one to implement. Wordpress was an obvious choice, but it offered a lot of functionality to I didn’t have or want, plus it was more complex than the others. I decided on MetaWeblog, with the Blogger API as a fall back for when MarsEdit tried to delete a post. It was surprisingly easy to implement, since almost all of the functionality was already in the other scripts, and Ruby provides an XMLRPC server out of the box.

The really nice part of all this is I now have the entire source to this site (flat post files + images + build scripts) in one Mercurial repository. I can download that and publish from any machine, as well as have instant back ups.

Not to say Postword isn’t without its flaws. The build script is slow; it takes a little while to generate all those archive pages that Wordpress creates on the fly. And if the build script is slow the publish script is glacial. When posting from MarsEdit, I can’t actually call the publish function after building the site, because MarsEdit will time out on the HTTP connection. That said, the pros easily outweigh the cons for me.

All in all, I’m tickled pink about how Postword turned out.

Lately it seems there’s been a lot of talk about distributed version control systems — especially git and Mercurial — and how they’re the bee’s knees or possibly even the cat’s pajamas.

But at the risk of having my programmer’s license revoked, I have to confess I don’t really care about version control systems. I mean, I think it’s important to use version control, but I don’t get all excited about the latest ideas in version control technology or the newest VCS on the block. It’s just a tool. It keeps versions of all my code, and allows me to revert to previous versions, see when and how things changed, and collaborate with other programmers working in the same codebase. Beyond that I don’t much care.

The tools don’t make the programmer.

What’s new with DVCS is the proponents seem to think they need to evangelize their system. Unfortunately they rather suck at it, and their arguments usually leave me feeling that I don’t want to use software used by such jerks, on account that it might make me into a jerk. Or at least a bigger one.

However, I do think that a DVCS can be a really useful tool so I’ve come up with some suggestions for those wanting to effectively evangelize their favorite version control system, or at least annoy me less when they talk.

1. Don’t be condescending or insulting

   I think it’s part of human nature — or at least programmer nature — to assume you’re the smartest guy in the room, and think that anyone who disagrees with you is a real buffon. Programmers seem to take great pleasure in showing that the other person is an idiot, or didn’t know something they did, or is at least not as clever as they are. A lot of arguments for git or Mercurial seem to revolve around explaining how git or Mercurial are so clearly superior that only morons would use something else.

   While this works great for rallying the troops, it’s counterproductive when trying to win someone over to your side.

   Think of it this way: suppose someone comes to your door to tell you about their religion. During the discussion they are self righteous and condescending; they don’t listen to your arguments, but are only interested in proving that they’re right. Are you likely to be swayed to believe in their religion? If you’re like the other hairless bipedal mammals inhabiting this planet you won’t be, even if they had some valid points.

   As soon as you become insulting or condescending, your arguments will be rejected out of hand. I know this will upset some programmers because they believe if you show your argument is superior, everyone will accept it. But that’s not the way people work.

2. Try to be helpful

   The best way to introduce someone to your DVCS is by trying to help them. Not in the “I have all the answers” way, but in the “I’ve dealt with that before, and here’s what I did” kind of way. People will run into the kinds of problems that DVCS are good at solving. When they do, you can helpfully suggest a solution.
   

   However, some care should be taken so the suggestion doesn’t come off the wrong way.

   Wrong	Right
   Dude, why are you using subversion?	I’ve run into that problem before. I solved it by using feature X of git/hg in this way.
   Dude, just use git/hg.	You smell nice.

   Be aware that people may not know where their pain points are. I’ve seen customers jump through some excruciating hoops to get a piece of software to do something when there was an easier way. People get used to pain and begin to assume it’s normal. If you notice something like that, even if they’re not complaining about it, you can politely suggest a better way.

   Instead of a list of features that a DVCS provides or abstract arguments as to why they should be using it, people respond better to concrete examples of how a piece of software can make their lives better. People are also more responsive when they know you’re on their side, trying to help them, even if they don’t — or currently can’t — take your suggestion. Keep in mind switching VCS in the middle of product cycle is likely something most people can’t do.

   The right attitude is that of trying to help a friend, not conquer an enemy.

3. Be willing to answer questions, even dumb ones

   Distributed version control works differently from centralized version control, and it does require a different way of thinking. I know I was confused by it when I first started looking into it. A lot of tutorials jump into the mechanics of how to perform certain tasks, but rarely talk about the philosophy of the system or why things are the way they are. If you want to successfully persuade people that your DVCS is the best then you need to be willing to do a lot of patient education.

   I say “patient” because after using centralized version control they might have difficulty switching over to a new mental model. Or they might have heard a lot of FUD about your DVCS that you need to put to rest. It’s important to do this patiently, respectfully, and not insultingly because they’ve picked up misinformation or don’t immediately “get it” like you do. Otherwise they might ignore your DVCS so they don’t have to deal with people who look down on them because they don’t “get it.”

4. Make it trivial to install and use

   This seems like a no brainer, but it is an important part of any software. If it’s hard to try out and use your DVCS, it simply won’t get used. I think that for the most part both git and Mercurial succeed in this respect. My only complaint is neither has a good Mac GUI client. Contrast that with Subversion which has both Versions and Cornerstone on the Mac. You shouldn’t underestimate the draw of an easy to use, beautiful GUI.

I think Joel Spolsky has given the best example of how to properly promote and evangelize a DVCS. He wrote a blog post — Distributed Version Control is here to stay, baby — about how he came to learn and use DVCS. It’s well written, and instead of condescending, he’s actually humble and admits he was wrong about DVCS to begin with. Joel also created a site called HgInit that does an amazing job of explaining the philosophy behind Mercurial and gives a solid introduction to right way to use it. It’s actually the site that convinced me to start using Mercurial for real.

[Note: This was the orginal post for my “professional” blog. It attempts to describe why I started a blog. It certainly wasn’t because I’m interesting.]

Or writing is hard, I should say. But “math is hard” is what one of my coworkers told me. I was trying to explain something technical (like how virtual memory works) when her eyes glazed over. I get that a lot. Anyway, she got some terms mixed up and said something like “so should I test the multiflange array for tacheon emissions?” Or something like that; I don’t really pay attention to the QA people. But her response to my laughter was “math is hard.”

Although math has never been all that hard for me, it did remind of what is. Writing. Being a software engineer I’m more used to communicating with computers in written form than humans. That means writing interesting specs or design documents or just communicating with coworkers is pretty difficult for me. Unfortunately submitting instructions via email to someone isn’t like writing a program to run on a computer. People don’t listen well and take exception to being called “buggy.”

Recently Joel Spolsky has been writing about the lack of good writing in the software engineering field. He’s asserted that good writing skills are essential to a software engineer’s career, and even compiled a book on what he considers to be good writing. Among his suggestions for engineers wanting to get better is something he calls “practice.” I decided to give that revolutionary idea a chance before Microsoft patents it.

So that’s the point. This is just practice. i.e. This is pre-alpha quality writing not meant to be used in a production environment. Use at your own risk, and keep all appendages inside the cart at all times.