Metablogging: How This Blog Works

This blog used to run on WordPress, but I was not entirely happy with it. I changed it to use Octopress (an extension of Jekyll) and I enjoy the writing workflow better now.

WordPress is a content management system, and as such, it does a whole lot of stuff. WordPress has a ton of built-in functionality and is well-tested. With plugins, you can add many things: from shopping carts to calendars to image slide shows. Other plugins can give you detailed permission models and auditing for posting or other complex functionality.

Advantages

I didn’t like WordPress for blogging for a few reasons (many of them very specific to my workflow.)

I prefer writing with Vim, and no WordPress functionality was going to easily replace this tool. This alone would probably be enough to get me to switch. Typically what I would do would be to compose a post in Vim, and then copy that into WordPress, do a little previewing to make sure everything looked good, then schedule the post for some future date.

Using a static site generator like Octopress or Jekyll enables me to use git. Git tracks detailed version changes across the entire blog (not just the posts). It also lets me work locally and then easily deploy when I am back online or finished. With WordPress I would have to connect to the server to be able to write. I can now even preview locally, something I could never do without an internet connection. Further, I can set it up so that preview updating happens whenever I save the file, so I can see how changes look in near-real time.

There are Markdown plugins for WordPress, but I found them inferior to local writing with Vim (no syntax highlighting, generally quirky behavior.)

As previously mentioned, WordPress has a great deal of complexity, and most of that I don’t need. This translates to being more difficult to maintain, slower load times, and increased server requirements. Generally most posts would load within a few seconds, but by hosting the blog on S3, this is down to tenths of a second. I think Google rewards sites whose pages load with extra link juice, so this is an extra bonus for doing the right thing (making your site load faster.) WordPress has caching plugins, but I found these to be flaky and sometimes display old content. I prefer having things be easier to debug and more deterministic by just showing what I have deployed.

WordPress is prone to security vulnerabilities. Unpatched sites are open to known security holes, and even sites running on the latest version are one exploit away from being turned into a rogue spam blog. With static sites, you know what content is up there and there are no ways to easily change it.

I am much more familiar with Ruby than I am with PHP. WordPress is built on PHP, and Octopress/Jekyll are built using Ruby. That fact means that if I need to extend the blog setup, I can more easily do that with one of the Ruby-based generators.

Although not much in either case, the cost of hosting a site on S3 versus a shared or dedicated server is much less.

Setting everything up

It took me a while to get set up, mostly because I already had an existing WordPress site with a few dozen posts.

Putting comments into Disqus

This is the zeroth step in the process. If you have comments on your existing blog, transition them to use Disqus instead. This is an easy way to port comments between the blogs. I don’t have good links since it has been at least a year since I did this, but the Disqus documentation is pretty helpful.

Getting up and running with Octopress

The first thing to do is to install Octopress.

Next, you want to import your existing WordPress posts. If you only have a post or two you might consider just manually copying them or abandoning the posts. Otherwise I recommend using a combination of WordPress export and exitwp.

I needed to ensure things looked correct when transitioned from HTML to Markdown, which took a bit of time.

Next, I took an Octopress theme that someone else made and copied it locally and made some modifications. I found this much easier than typical theme development on WordPress since it was clearer what the CSS referenced.

Merging down my ‘debugging’ blog

I used to have a ‘debugging’ blog that was for development thoughts and Stack Overflow-esque error statements that was at http://22ideastreet.com/debug while my normal blog was at http://22ideastreet.com/blog. These were maintained as two WordPress blogs, but getting Octopress/Jekyll to compile these together was tough. I ended up using a hacky Octopress issue suggestion for awhile to have the two blogs separate. This required me to have the debugging blog generate to a subfolder of the main blog, and then to add that output to the main blog’s git repository, and then to redeploy it whenever I wanted to see changes or to publish.

This was very unsatisfactory. I ended up freezing the debugging blog and writing a little extension to take the old posts and put them in the right place, and will just continue working on the main blog in the future.

Fixing comments

It is important to make sure that your blog URLs are in the same place as they used to be so any external links point to the right place. Again, this took a lot of time that a normal fresh install might not have taken since I had two blogs going to the same domain. Octopress by default only uses one Disqus URL, so I had to tell my old ‘debugging’ blog posts to use a different URL to point to the correct blog. Disqus does not have a way to merge two sites (I asked.)

Publishing

I used a script that Wes Winham made that pushes static assets to S3 and modified it slightly. Publishing to S3 is now a one-command process.

Drafts

The only thing I was missing was drafts and post scheduling. I rolled a draft system using Chronic. Workflow:

 $ rake "new_draft[How This Blog Works]"
  mkdir -p _drafts
  Creating new draft: _drafts/how-this-blog-works.markdown
 # write.. preview..
 $ ./bin/schedule_post _drafts/how-this-blog-works.markdown "Tomorrow at noon"
  Scheduled at: 2014-02-20 12:00:00 -0800
 $ git add -A
 $ git commit -m "Write metablogging post."
 $ git push

Then I have a local Jenkins install running a script hourly to fetch the private Github repo and see if any posts needed to be published and, if so, publish them and email me. This has worked extremely well so far.

Issues

I had some issues early on with RSS flooding existing subscribers with posts every time I pushed or published. I ended up just putting one post in the RSS feed and having the time not be put in there based on when the site was generated, but instead when the post itself was published.

In retrospect, I think going with plain Jekyll and customizing it may have been a better choice in the long run. I think that since Octopress may be updated less frequently or abandoned as time goes on. However, for this time it works just fine and a lot of the work of transitioning from WordPress is already finished so it would be easier to switch to another platform. I have the wedding website as another static site just using Jekyll, and that worked out well.

Your turn

What do you use for blogging? Do you like it?

What things did I mention here that need more explanation? What would you like open sourced?

Compelling Reasons To Fly Southwest

I’ve been doing a fair amount of flying in the last year, and Southwest is currently my favorite airline. In this post I will list reasons why Southwest is the best (in order of importance) and one thing I’d like to see improved.

Biggest Benefits

Liberal reschedule policy

Probably the biggest benefit to me has been Southwest’s liberal flight rescheduling or cancellation policy. On many other airlines, changing or cancelling your flight reservation (whether it is days or months away), will cost you hundreds of dollars. Have something come up at the last minute? Well, you’re out a hundred bucks to change your flight by an hour or two. You can pay much more for a refundable ticket as well.

Southwest does not have this restriction, so even if you pay a little more for your ticket, if you use this option one time, you are going to come out ahead. Worst case, if you cancel, you get a credit to apply to future Southwest flights.

Intelligent boarding

Another huge reason to fly Southwest is that it has the most sane system of any airline that I have flown to get people on the plane. There are three components that are all tied together: online check in, boarding, and seat selection.

Typically getting on the plane is a long, drawn-out process whereby you have a number of prestigious tiers and then finally you get to get on the plane. Passengers gather around the gate in some sort of cluster waiting for their group to be called, and then try to push past each other to get the opportunity to sit in their already preassigned seats instead of spreading out in the spacious airport with power outlets. I don’t see much benefit to checking in on other airlines.

Instead, on Southwest, online check works in first-in, first-on order. If you check in before others, you can get on the plane earlier. This is actually an advantage because you pick your seat when you get on the plane. There is a small queueing area where passengers line up in numerical order based on check-in time, and you just go on the plane in line order.

Want to sit by your friends or family? No worries, you can probably arrange it. Either book together and your check-in numbers will line up. Or get on the plane and you can probably hold a seat for them especially if you sit toward the back. Or maybe you could board later with them. Selfishly, I like that people who check in online the most quickly get the best seats, as I am generally by a computer with email so I get a jump on the crowd. I can see how this would benefit Southwest, as more people would check in earlier so they have more information on who is still planning on traveling.

One nice emergent effect of this system is that the aisle and window seats generally fill up first. If the plane is not full, you get maximal spacing between passengers.

Free snacks

No more being hangry on the plane. On somewhat long flights you will get free snacks, and not just peanuts. You can choose different types of crackers, cookies, chips, pretzels, and the like. The flight attendants are very generous with the snacks. Often they encourage people to take some more, or say “Come on, this isn’t Delta!”

“Bags Fly Free”

I haven’t needed to use this yet, but it’s nice to know that it is an option if I’m doing some serious travel. While other airlines charge a hefty fee per bag, Southwest lets you check a couple for free.

Other niceities

No drink cart

Another departure from the status quo that seems to make more sense is that the flight attendants don’t roll a hefty drink cart down the aisle to deliver drinks. Instead, Southwest staff take orders for a few rows on some sort of handheld device and then go back to the stock room and get drinks to deliver.

This approach has a few advantages. First, you can’t get bumped by the cart. Second, you don’t get blocked by the cart, so bathrooms are more open. I find it a bit more personalized and clean. It seems like they can probably store more things in the stock room than on the cart, and generally seems a bit more lightweight. I would even dare to say it is a bit more Lean, in that you are delivering things via a pull system rather than a push system.

Pretty big seats and fun attitude

I find the seats to be spacious relative to other airlines on the planes that I have flown on, and the boarding order strategy means that good seats (exit rows) are easier to come by for the same price as normal seats.

I generally like the crew’s attitude on the planes, it seems like they are having fun without being too much in your face about it.

Possible Improvements

About the only thing I’d like to see would be free Wi-Fi. They already have gate-to-gate Wi-Fi for eight dollars a day, but having it be free or baked into the ticket would be even better.

Anyone have any tricks for free Wi-Fi, or any good travel hacks to share?

Floobits for Remote Pairing

I tried a new tool with Kyle Shipley recently, and it has proven to be interesting and useful.

Floobits is a recently-created remote pairing solution. Imagine wanting to pair with someone and they are across town or in another state.

I enjoy pairing remotely, as it lets multiple people work together even when they are not colocated. I think that pairing is a great way to share knowledge on a team and reduce defects by promoting accountability and quick feedback. Further, I think that remote worker morale increases when talking and working with teammates.

Kyle and I used Floobits to pair on a random coding project, and I found the entire experience compelling enough to get past the set up and some early wrinkles. With Floobits, you create a shared workspace that other people can view (public or invite-only). You install a plugin to your editor and maybe a custom build of the editor. Then when you make changes to the file, diffs of the code are sent up to a server, which then propagates to anyone connected.

image of using Floobits

Existing solutions

There are some solid existing solutions out there like sharing tmux or screen sessions.

I won’t go into certain things like Skype screen-sharing. In my opinion, both people pairing should have the ability to edit at any time except for very short sessions. I find it frustrating to have to spell out exact changes when I do not have control, and I think it is asymmetric enough to warrant looking for a better solution when the “pairing” will need to happen for more than an hour.

Positives of using Floobits

However, I think there are some unique advantages that Floobits has specifically.

One of the best features of Floobits is being usable across multiple different editors. For example, I like using Vim, and my partner can use Emacs or Sublime Text. I really like this over being forced to use a common editor.

Since I can use my preferred editor, all of my custom key mappings and settings work locally. This is useful because the muscle memory is preserved. You might even find that one editor or person is more effective at making certain changes (say, replacing text or reformatting markup.)

Being cross-editor and just sending file diffs to a server means that the service is cross-platform as well.

There is minimal setup and learning curve. Basically you just install something and you can use your local editor like normal. This seems preferable to bringing on someone and needing to get them up to speed with tmux’s commands before being fully productive. For consultants, this could be fantastic for working with people from different organizations and being able to let each side use the most productive environment for them.

Both people can edit concurrently, which saves time and sanity. We can both spike out a feature or syntax and see which way looks better. There is no need to coordinate ‘driver’ and ‘navigator’. I can even look at different parts of the code while other parts are being edited, which increases engagement. Compare this to being locked into whatever view our pair is looking at when using tmux. Just like Google Docs, the changes are propagated to the other person’s editor without needing to save. Even in Vim, I see the other person’s cursor moving about. Wondering how they do that…

Worried about getting off track and not knowing where your partner is? No need to worry – your editor now has a special command called ‘summon’ that will ask all attached viewers to look at the current file and line where your cursor is. There is also follow-mode, which makes your cursors follow theirs so both people type and see the same thing.

The web version has a full code editor, so you could conceivably edit from a mobile or tablet device. Rounding out the features, you can use a shared terminal which either person can type commands into and see the results of running. Floobits also integrates with Google Hangouts, so you can have everyone connected and not need to coordinate that setup. So far we have just used Skype, but Hangouts seem like a nice integration.

Possible negatives of using Floobits

Not everything is rosy, and there are some shortcomings at least at this time.

Syncing files between machines can be a bit flaky at times. There have been some ghost files that just show up and are hard to get rid of. We sometimes can’t figure out if it’s syncing too much or not enough. Sometimes I will have a new file locally that seems like it doesn’t get synced up for a little while.

Obviously the codebase of the editors and service is fairly new, so there are random display bugs and so forth, but I would imagine that these would improve over time. No show stoppers yet.

Sharing code with any external service means that they could conceivably look at your source code. So you need to consider the security of this in the event that you work on valuable code on Floobits (even in a private environment.)

While I found the shared terminal to be useful, it can be slightly risky. For example, anyone who has edit permissions to the project can type rm -rf something and cause some damage. It would be interesting to explore a different model that has your environment in a sandbox of sorts, even at the cost of some flexibility. That said, you should probably only open a shared terminal with people you trust at this point.

Extensions

For companies or individuals that advocate transparency, live coding on an open source project in front of the world is a great way to be transparent. Anyone can connect to a publicly accessible project, so you could get people who follow along and might want to help out coding. It could be someone interested in the project and how you are coding it, or maybe someone who is trying to advance their own skills. Moreover, it could be a good avenue to find new pairing partners.

I could see conducting live code interviews using Floobits since it allows people to code in whatever editor they feel most comfortable working in and has a shared terminal to view test results. Sharing editing privileges are not even necessary, the workspace could be read-only.

#pairwithme :)

Write a Test Before Disabling Code

Today’s short idea is: before you hardcode a value or comment something out for debugging purposes, write a test that ensures that you change it back. This way you break the build if you commit the change.

The thought here is that if the functionality is actually important, there should probably be a test for it.

Of course, it is useful to weigh the long-term costs of maintaining a test like this. There are other stages in your process that can also catch these sorts of defects, including:

  • inspecting your diff before committing (git diff and git diff --cached)
  • incrementally staging changes (git add -p)
  • doing code reviews (still not foolproof!)
  • having other tests that detect the change
  • making small changesets to make the change easier to spot
  • having smoke tests or business metric tests

It may be useful to write the test and then remove it once your small change is reverted. If this test is the only one that fails when you change an important configuration setting or code value, it might indicate that there was initially a useful test missing.

Increasing Cashflow in a Software Consultancy

Here are some basic thoughts on improving cash flow on successful projects, which should be applicable to many freelancers / contractors / consultants.

Possible current problems

Payment latency

Invoicing is generally kind of a pain because you have several gates to get through in order to get paid. You could be looking at the following situation if your company has net-thirty payments:

  • Work done on day 1
  • Company policy is to bill the client every thirty days, so we send the invoice for days 1-30 on day 31
  • Our invoice is on net-30 terms, which means the client has thirty days to pay the invoice (day 61)
  • We notice the invoice has not been paid on day 65 and send an email reminder
  • The client promptly sends a check via snail mail. We receive it three days later (day 68)
  • We deposit the check on our weekly bank run (day 70)

So with these policies and delays, we could easily be looking at seventy days between when we do work and when we get paid. One issue with this is that it gives us a slower feedback cycle on the work that we are doing.

Startups considered harmful to cashflow?

I’ve heard something along the lines of this story a couple of times:

We started work with [startup X] in April and things were going well. They paid on time and were generally a pleasure to work with. Then they started falling behind on payments, but they assured us that payments were just around the corner. Finally we had to cut them off because they were avoiding us, but unfortunately we have a couple of months worth of unpaid bills on the project. Now they are saying that unless they launch soon with a few more features, they won’t be able to get more funding, and won’t be able to pay us.

So now the consultancy is in the unenviable position of:

  1. writing it off and losing a couple of months of money
  2. trying to help just a little more and taking the risk of losing whatever leverage they might have had

I liked Brennan Dunn’s perspective on considering equity:

I make it very clear that I’m a professional, and my job isn’t to take on risk. The founders and their investors are on the hook for either crashing or burning or making a boatload of cash; my job is to get paid for services rendered.

Taking equity further harms your position, as you get into “between a rock and a hard place” decisions a bit more often. It also exacerbates cashflow issues, as equity pays out generally only on a liquidity event, which may be years from now (if at all.) Try paying for dinner with equity from a pre-IPO company, and you will see what I mean. :)

Some potential solutions

Getting better terms

Alan Weiss has written some excellent books on consulting including Million Dollar Consulting. I definitely recommend reading it, as it will force you to look at your business assumptions in a whole different light.

Weiss promotes getting better terms for your contracts. He requests that all clients pay upon signing a contract with him for the full fee. For a monthly retainer, he might book for six months or a year. For a full reason of the benefits, I encourage you to check out the book.

I enjoyed these posts by Sebastian Marshall on thinking through the systems behind fees:

Creating better internal systems and policies

I recently started depositing paper checks with my phone to avoid needing to go to the bank (to cut down on the amount of delay in the money-getting workflow.) What other things could you do to cut out delays entirely caused by your end?

Do you invoice monthly? What about cutting it to biweekly? This would certainly help to reduce the risk with minimal impact on client relations. Same for payment terms, doing something like net-15 instead of net-30 should be no problem for a client that you are meeting with every few days anyway.

I recently highlighted using IPN to get faster payment of invoices. Through IPN or other means you can give an incentive for timely payments, although I probably would not do that unless I charged higher than usual to begin with (a form of fees for late payment.)

When you consider that you develop software in an iterative manner to reduce risk, why not bill for that software development in a manner that reduces the risk?

Get payment up front with riskier clients

To avoid the aforementioned client with financial problems, consider taking advance payment. If you have a lot of potential paying clients and an existing client misses paying an invoice or two, you can consider making prepay the default for that client.

This may seem heavy-handed, but you have a business to run and should not be in the business of making loans. If I have ample clients, then those that are not paying in a timely manner need to get current and stay current or risk losing trust.

What if you don’t have a good idea of what to charge for a prepay block? You could look at past billings and make an educated guess, charge a certain amount and then invoice for the overage or apply the credit to the next month, or allow prepayment for a block of hours.

Prepay for a block of hours

Jared Brown taught me about a “prepayment for a block of hours” technique. Basically low-bandwidth clients purchase a block of hours (say, ten hours) and then they can use these hours across whatever issues come up. I suppose this is a sort of a retainer with a time cap. It is useful when the scope of work changes often or there are budget concerns. The client knows they will be paying for X hours and can get the changes they need, and that more work will cost more.

This strategy incentivizes clients to be clear about their scope of work and desired results. It’s also nice that you have the funds up front instead of needing to worry about tracking someone down for ten hours worth of work. In a sense, it’s batching up small payment decisions into one larger contract, and also bundling any authorization decisions in there as well. “I’m getting close to my limit, so I’m going to need you to sign off on an additional Y hours.” When you get paid, then you work. Not the other way around.

Other thoughts

Obviously I seem to be focusing on hourly / daily compensation, which leaves out the value-based fees approach. I think that some of the principles are similar though, and I think there is value in considering how you can get better terms and make better policies and systems.