Webby – Client-side, static content management system

This afternoon I rebuilt OasisDigital.com using Webby, stripping out hand-coded HTML and replacing it with much more maintainable Markdown. The site looks about the same as before (which is to say, mediocre), but under the hood it is much easier to update. We intend to use this new ease, to move forward in improving it. There is a general principle here, which applies broading in software development also:

If you need to make a change, but that change is difficult / tedious / risky to make, first improve the underlying system that makes it so.
(OasisDigital.com is a static web site; we have dynamic contact (issue trackers, etc.) to automate our work together and with our customer, but that content is on another domain.)

Webby is a client-side, simple CMS for generating static web sites, written in Ruby. Why serve a static site (plain old files on a web server) in 2008?

  • It minimizes the moving parts, there is almost nothing to break or maintain.
  • It is very unlikely that any hosting issue will break a static site.
  • It is easy to serve a static site fast (though our current host, TextDrive, sometimes is not all that fast).
  • Security vulnerabilities are very unlikely, in the absence of any executable content.
  • The canonical content (in this case, mostly Markdown) is stored in plain text files, which we track, diff, and merge in git.

In an earlier foray in to Drupal, we found that Drupal has extensive and useful capabilities, as well as a vibrant community, but it also has many moving parts; too many, in my judgment, to make it a good solution for building an essentially static web site.

Git Talk at the STL JUG

Yesterday (Oct. 9, 2008), I gave a talk on Git at the St. Louis Java User Group. Rather than a typical “intro” talk, instead I showed a dozen or so common usage scenarios, then answered questions with additional ad-hoc demos. As with some other recent talks, I eschewed PowerPoint in favor of a printed handout. The text of the handout follows below, or you can download the PDF. I also recorded the audio of the talk, but without video, so the general discussion portions are worthwhile but the demo portions are not.
Continue reading “Git Talk at the STL JUG”

TDD, Still in Style?

Test Driven Development doesn’t seem to be in style today to the extent it was a few years ago. I think that’s a shame, because TDD is among the most powerful ideas I’ve come across to boost the quality of the software we deliver. At Oasis Digital we even use it in unusual places, like this Palm application we develop for a customer:

This application forms the core of our customer’s business; they sell it at a commercial product to their customers, who use it in high-pressure situations. Over 4 major versions and 4+ years, there been remarkably few bugs or other issues found “in the field”, which I credit to:

  • Use of automated testing
  • An overall level of care and attention to quality

The second item alone is not enough. To achieve quality you need to do more than have the right intentions and work hard. You need to do the right things.

Rearranging files in SVN? Use git-svn instead.

From time to time I need to rearrange a set of files in a project, typically while revamping the file / directory layout of a set of source files. The most direct way to do so is by dragging the files around (using a Windows or Linux GUI), but this is quite tedious to do if the files are in a Subversion repo, because SVN does not understand the file moves and renames unless you use “svn mv” or (with TortoiseSVN) right-click-drag the files to new locations.

The answer to all this is simple: use git-svn for your SVN checkout, instead of the SVN command lines tools or Tortoise. You can readily Google for extensive git-svn information to get started.

The workflow with git-svn for file rearrangement is fairly simple, and very fast:

  • “git svn rebase” to get your local git repo up to date with your SVN repo.
  • make new directories, rearrange files, rename files, etc., using any tool you like. This is easy and painless because git (wisely) keeps all the metadata in a top-level .git directory. It is fast because you aren’t running any svn code (or any git code) while doing so.
  • use “git add”, or the git GUI, to add the newly moved / renamed files.
  • “git commit”
  • “git svn dcommit” to push the changes over to SVN.

git / git-svn looks at the content of files, notices (rather than you needing to tell it) that the content has been moved to different filenames in different directories, and generates SVN move/copy operations. It even notices nearly-identical (edited) files and handles them correctly.

One loose end is left hanging, which is that git-svn does not remove any now-empty or removed directories from SVN, a consequence of git not caring about directories. Therefore, if you need the empty directories removed from the SVN repo, use a normal SVN client (command line, Tortoise) to do so.

From the description of above, this does not initially sound like a big win; but with hundred of files to move around, the time for the git commands (instant, except for the first and last) is irrelevant, and the time/hassle saved is enormous.

Perhaps someday SVN itself will gain the ability to “just work” when you move or rename files / directories, rather than having to be told.

Need text? Hire a Writer

To help create the document I mentioned earlier about the merits of custom software development, I hired a subcontract writer. The only typing I did was a bit at the start and perhaps a half-hour of editing at the end; all the rest of my input was in the form of spoken-word audio recordings, which I find fast and easy to create.

A critical factor in making this worthwhile is the categorical difference between a writer and a transcriber; I’ve used transcription services with excellent results, but a transcribed talk is far different in form and polish, than purposefully written text. The process was roughly like so:

  • I posted an ad on Craiglist to find a technical writer
  • I wrote short notes/outline of the topic
  • I recorded an audio ramble of my ideas for the content
  • Writer sent me draft #1, organizing my ramble in to a coherent form
  • I recorded audio feedback
  • Writer sent me draft #2
  • I recorded audio feedback
  • Writer sent me draft #3
  • I made a bunch of edits, and posted it

This worked out well, in several ways. The first, minor payoff is that it took a bit less time than just writing it myself. In retrospect it was only a minor time savings; if I had just sat down and wrote it all myself in one go, I could have finished in a handful of hours.

The second payoff was much larger: although I could have theoretically done it all myself, most likely I would not have done so yet. My personal threshold to get started and keep the process moving was much lower. Engaging assistance transformed an idea for what could happen, in to a process that did happen.

The third payoff is that this process is another useful tool in my toolbox; there is a big difference between know that I could use such a tool, and having actually done so.

Thus, I consider the experiment a success, and will almost certainly use the same process on more projects.