TaskPaper: Insert Started Tag

It’s not really enough knowing when you added a task to your list and know when it was completed. I mean, it always feels good to wrap something up, but it’s incredibly helpful to know how long that thing took to complete. Over time, you can use the ‘working time’ metric to tune your pipeline. Besides, I really dislike leaning back in the chair to rack my brain in order to remember exactly when I started working on a task. It’s also nice knowing how long something sat around waiting to be worked on. That’s why I whipped up Insert Started Tag.

on get_date()
	set currentdate to do shell script "date +%Y-%m-%d"
end get_date

tell application "TaskPaper"
	tell front document
		tell selected entry
			make tag with properties {name:"started", value:my get_date()}
		end tell
	end tell
end tell

Finding Clojure By Playing On The Seaside

The Technitai blog has been far too quiet for far too long, but it’s been because I’ve been burning the midnight oil learning a brand new, for me, way of thinking.

Late last year, I began compiling a list of programming languages and frameworks that I thought that I should at least know a little about. As part of this process, I  sat down with a project idea – a player/event management app for Firefight! That way, I could explore the problem domain and I knew where I could get a subject matter expert if I needed one. Early this past spring, I started digging in.

I started out with Opa, but didn’t get very far. Adam Koprowski, over at Opa HQ was very helpful with answering my early questions. But a few things made it difficult for me to gain traction with the language. The Opa project was transitioning from a Caml based syntax to one based on JavaScript. At the time, the documentation was split between the two which made the going quite rough as I have zero experience with Caml. Compound that with an inexperience in functional programming – well, sit back and imagine the soothing sound of grinding gears.

Opa, I shall be back. Oh, yes. I shall be.

I moved on to Seaside on the Pharo Smalltalk implementation. Six or seven years ago I attempted to dabble with Seaside on Squeak. I wouldn’t call it a crash-and-burn experience but I got nowhere fast. This time around things were totally different. I made some serious headway on the project and I fell in love with the expressiveness of Smalltalk. Years ago, the intrinsic coupling of the language and its environment threw me for a loop. Now I totally appreciate it for its elegance and empowerment. Seaside as a web framework is a stroke of genius. Couple Magritte with Seaside and you’ve got an extremely potent one-two punch for capturing and validating form data on the web. At the conclusion of the prototyping sprint, I felt like I developed an actual application rather than a collection of web oriented components. I thought that I had found my way of developing web apps.

Okay, two more languages were on the short list to check out: Scala and Clojure.

Scala looked the less exotic of the two. The biggest difference being not-LISP. Its syntax didn’t look all that far off from Python and Ruby where I felt quite comfortable. The functional bits could be ignored and used when desired. Kinda like how I was using JavaScript. Besides, it was Lift that put Scala on my RADAR to begin with, so I started heading off in that direction. But something made me pause and reexamine where I was headed.

Each week, I receive The Pragmatic Bookshelf monthly email filled with info on releases, news, and their PragPub magazine. That month they just released Programming Clojure (2nd Edition).

I remembered stumbling onto Clojure when it was new and noting to myself that I should learn-it-someday. I was of course intrigued by what I perceived as its arcane LISPness that verged on the mythical. Back then it was a someday-language. A language to learn someday when I’m suddenly smart enough to learn it.

I bought a copy of Programming Clojure and examined the Clojure web development field but didn’t find a counterpart to Seaside or Lift. Instead, I found stuff called RingHiccup, and Compojure. All of the moving parts had me a bit confused. What was I thinking? Then I found Noir:

Noir is a micro-framework that allows you to rapidly develop websites in Clojure.

And it couldn’t be any simpler.

Sold!

In less than a day, I put my eyes on every character of every word of Programming Clojure. After the once-through, I didn’t intimately understand everything that I read but I got it. On day two I began coding. There were some fits and starts and sudden stops, but soon, I gained some real velocity. After prototyping the Clojure project to be as close as possible to the one done in Smalltalk, I took a step back and thought that while it looked the same in the browser, it was relatively primitive underneath. At first, I thought that I went backwards. But I soon learned that this was a instead a strength.

I did a quick survey of what JavaScript frameworks were out there for building modern web apps. I went with AngularJS. It turned out to be an excellent fit with Noir.

Using AngularJS, I “modernized” the prototype and soon its functionality surpassed the one done in Smalltalk and Seaside. But even more importantly, I understood what Halloway, Bedra, and Hickey were talking about. The lingering doubts that I had about OOP modeling, all the while that I thought that I was good at it, were gone. To top it off, my code base was smaller and just as legible. Don’t get me wrong. My code was quite unpretty here and there and organization in places left much to be desired but those were things that I knew how to fix. And I could fix them without the fixes rippling out across the rest of the system. I freaking learned Clojure!

Okay, back to the mission. I didn’t want the exuberance of learning Clojure to limit my appreciation of Scala so I jumped into it headlong.

There are a lot of good Scala tutorials on the ‘net but I homed in on Programming Scala at O’Reilly. The book itself is a good value too, by the way.

The first thing I did was create a new Scala project to parse the Firefight! ePub in order to pre-populate the database with stuff. I had a heck of a time getting sbt, the Scala Built Tool, to download the project dependencies. Eventually, I gave up and just downloaded them manually. But I did get Scala to parse the XHTML and to insert data into MongoDB.

I’m totally sold on Scala as a scripting language. Having access to all of the libraries that run on the JVM is a huge boon.

As I worked through Programming Scala, I couldn’t manage to gain velocity on the prototype project. A ball of frustration grew inside of me because, as a language, Scala looked familiar. The functional parts were empowering. Traits looked, to me, lightyears ahead of Java Interfaces. After coming off Clojure, there seemed to be so much code but I could have gotten over that if I had a better experience with the build tools, and hadn’t encountered binary incompatibility with compiled libraries, all the while trying to learn both a language and a framework at the same time. It simply felt like too much, and I ran back to Lein.

Scala, Lift, and the Play! framework are all obviously powerful and I’ll be revisiting them before too long, but I’ve decided to build my app prototype into a full blown product using Clojure.

So, yep. I found Clojure by playing on the Seaside.

FIREFIGHT! Oscar Mike

The website for our game FIREFIGHT! has launched. It has been a lot of work but so worth it. I touched everything from logo design to line height and danged near everything in between. Writing content was perhaps the most difficult part. For a while now I’ve been working on my visual design chops but writing for an audience is a much more recent turn for me. It’s tough! I have an improved but not new respect for those who do it every day.

The site itself runs on Drupal within the Acquia Drupal Gardens cloud. I’ve been impressed not only with the stability of the site but the pace at which the Acquia guys are rolling out new features. For example, they just released functionality to add custom JavaScript frameworks to your site. Nifty.

Back when I was a systems administrator I maintained a Drupal install. The Acquia team does it better than I did or could do today.

Some parts of the process were painful. Working with the built in rich text editor proved difficult and a majority of the time I worked outside of it using apps like TextMate, Espresso, and the amazing CSSEdit. Along the way I picked up a few techniques like editing live within Firefox with Firebug to do rapid prototyping. I think there’s a blog post or two in there somewhere.

Anyways, check out the site and let me know what you think. Feedback is always appreciated.

Gamestorming the Benefits of Firefight!

We’re at the stage now with Firefight! where we’re really working on marketing. I’ve got to be honest with you, it can be tough for me. It’s not a moral issue. It has more to do with spending so much time creating and fabricating that it’s a big context switch. Sure, we’ve established strong design goals but those don’t typically directly translate to benefits or even features that a potential player can relate to. How did we translate those technical bits of game geek speak into benefits and features? We Gamestormed it and went from this:

To this:

It was inspired by the Cover Story game. But instead of using it to bring forward new ideas we used it to jump in and focus on what’s important from the perspective of potential customers.

The Skinny On Agile Game Design – Part 3: The Firefight! Board

In the previous Agile Game Design post we covered how to create a basic Kanban board that could be used for just about any endeavor. This time we’ll take a look at a board used specifically for game design. It’s the one that we use here for Firefight!.

Definition of Done

This version of the Kanban board has something new that we haven’t seen yet, Definition of Done.

Each column has its own definition that items in that step must meet in order to be called done. The definitions not only help to get everyone on the same page but they also act as reminders.  For example don’t worry about formatting and paragraph spacing when working on something in development. That’s not part of Development’s definition and odds are that it will be wasted effort.

The definitions are not meant to be inhibiting. If they are then they have to be changed. They’re there to facilitate getting things done  while protecting product quality.

The Columns

Next

The items stickied in this column are pulled out of the backlog that we manage off-board. In our case we use Circus Ponies Notebook.

Think of Next as a slightly more sophisticated To-Do list where items of higher priority (as compared to those still in the backlog) are staged on the board.

Analysis

Work In Progress Limit: 2

Items pulled into this column are analyzed to determine if they really are what we think they are.

If an item is too large (too many parts) to flow across the board then this is where it gets split into smaller chunks. Priority chunks are left here (respecting Work In Progress limits) while the rest are moved back to Next.

Next and Analysis function together to minimize wasted effort down the line.

Definition of Done:

  • Goal is clear: The objective is set. The item’s purpose is known.
  • 1st tasks defined: This is about creating momentum. When the item is pulled into Development the developer can get started right away. He doesn’t have to make any guesses.

Development

Work In Progress Limit: 3

This is where you make sketches of ideas and hash them out. The skeleton of ideas get flesh put onto them and are molded according to vision. At the end of this stage they only have to be beautiful ideas not pretty to look at.

Definition of Done:

  • Unambiguous: In context of game design this means that the item or rule can be understood by others.
  • Component is captured: This means that it has been written down or is in an application available to everyone on the team.
  • Integrated and Tested: The item or rule makes logical sense and does not introduce unintended consequences.
  • Ready for Write-Up: The item is ready for the next step.

Write-Up

Here is where the product of development is refined for release.

Work In Progress Limit: 3

Definition of Done:

  • Written for final presentation: The item’s text is ready to be read by the outside world.
  • Retains design intent: Nothing was lost in translation.
  • Ready for acceptance: The item is ready for the big review.

Acceptance

Items pulled into Acceptance are looked at with a discerning eye. If they pass muster then they are given the thumbs up and are moved off the board and logged. If it’s thumbs down then we begin exploring the reasons why so that problems can be addressed.

Definition of Done:

  • Reviewed and given Thumbs-Up.
  • Ready for play.

Wrap-Up

So there we have it. The Firefight! Kanban board for developing ideas into functional game components fit for use in the field.

But wait a second! Where’s a Play Testing column? Isn’t testing important? Heck yeah it is. Our old board had one when we were doing active play testing. But we’re beyond that now and our board reflects our current workflow. That’s one of the nifty things about Kanban. It fits you.

From Scrivener to EPUB

Outside of the technical arena I’m smack dab in the middle of writing a game book. Up to now it’s been distributed as a PDF but the workflow and distribution has been anything but agile. So, the decision was made to turn it into an HTML5 mobile app that we could iterate over and push the updates to customers. On the way to HTML5 we decided to turn the whole thing into an EPUB. We’d have the chapters already broken up into separate HTML files and we’d have a new product. Talk about limiting waste.

Scrivener is an excellent app that we use for outlining, editing, storyboarding, and writing. It exports to multiple formats; PDF, RTF, Word, EPUB, HTML, etc. Scrivener’s EPUB export works really well for quickly getting your book packaged up. But for us there were a couple of issues. The conversion to HTML is handled by libraries from the OS and it does enough funky stuff to make future reuse of the exported markup difficult. Looking at the resulting markup, one time a header is a header and the next it’s a font whose size is set to 180%. That kind of thing makes it really tough to apply sensible custom CSS. But all was not lost.

Scrivener also compiles books to MultiMarkdown which can be transformed into very clean HTML. To leverage the Scrivener-MultiMarkdown combo I wrote a set of scripts called XHTML2EPUB. The scripts convert the Scrivener generated MultiMarkdown file into a standards compliant EPUB file ready for distribution.

What does MultiMarkdown look like?

Here’s a very basic but straight forward example.

## Playing The Game ##

The Firefight! Tactical Roleplay Engine requires at least one OPFOR Commander and a small group of players; some playing as the Operators and the rest helping the commander by playing as OPFOR.

The text surrounded by double hash marks are denoted to be a second level header.

When rendered as HTML it looks like this:

Playing The Game

The Firefight! Tactical Roleplay Engine requires at least one OPFOR Commander and a small group of players; some playing as the Operators and the rest helping the commander by playing as OPFOR.

Piece of cake and very easy to work with. We converted the entire project to MultiMarkdown by hand instead of relying on the built-in WYSIWYG tools. You tell MultiMarkdown what you mean the text to look like instead of worrying about font selection and what-not. Beyond making it easier to apply custom CSS, I’ve found that this approach makes it easier to focus on the writing itself. WYSIWYG can be distracting.

Here’s more information on creating a MultiMarkdown document that’s straight from the source.

Setup

Before you can run the scripts there are some things that you have to make sure are installed:

  • MultiMarkdown Select the installer for your operating system and have a go.
  • Ruby If you’re running OS X or Linux then odds are you already have it installed. If you’re on Windows then have no fear. It’s a straight forward install.

Installing the necessary Ruby bits

From a terminal/command line run the following lines:

gem install nokogiri
gem install uuidtools

Depending on your setup you may have to use the sudo command. For example:

sudo gem install nokogiri

And so on.

The Workflow

1. Compile your work to MultiMarkdown

In Scrivener select Compile… from the File menu.

Note the document titled Meta-Data. Here is where you can place bits of information useful to Multimarkdown. Make sure this bit is in there:

css: ../Styles/epub_style.css

Under Formatting, at top of the representative text area, add:

# Title #

This tells Scrivener to insert the chapter title as a header element into each chapter’s text. You could do this step by hand but you lose the ability to freely rearrange chapters within Scrivener via drag and drop.

XHTML2EPUB uses this bit of information to do its thing.

2. Configure XHTML2EPUB

3. Run mmd2xhtml.rb

mmd2xhtml.rb is included as a convenience script to convert the file denoted by multimarkdown_file_name into plain ole XHTML. After this script is run there will be a monolithic XHTML file in the master_directory. It is split into individual chapter files in the next step.

4. Run xhtml2epub.rb

This is where most of the work is done. After you run xhtml2epub.rb you will have a complete working directory for your EPUB with all of the assets; text, and images all in the right place. The script also massages the generated HTML to comply with EPUB standards.

5. Tweak the CSS

Since EPUB is styled with a subset of CSS 2 you can use your favorite editor to tweak epub_directory/OEBPS/Styles/epub_style.css.

Once everything looks good simply run xhtml2epub.rb again and it will scoop everything up and recreate the EPUB file with your CSS changes.

New TaskPaper Script Location

As of TaskPaper 2.2.6 the app’s script menu has been removed. This means that we’ve got to move our scripts to where they can be accessed from the script global menu. I moved mine to the following location:

~/Library/Scripts/Taskpaper/

The Scripts icon lives in the menu bar up by the clock. If you don’t see it there you can turn it on by going into the AppleScript Editor preferences and checking  ‘Show Script menu in menu bar’.

And voila:

Hint: You don’t have to go hunting for the AppleScript Editor in the Finder as the easiest way to launch it is to type its name into Spotlight.

The Skinny On Agile Game Design – Part 2: I Think I Kanban

In this article we’ll create a basic Kanban board that can be used for game design or just about any other kind of project. But first…

What is Kanban?

Kanban is a bit of a complex term. It is both an approach to development, in our case, game development, and it is also literally means “visual card” in japanese.

A Kanban board is a visual representation of your design workflow that uses cards or stickies to represent individual features (and sometimes tasks) to be completed. Cards are affixed to and flow across the board as work progresses. Let’s take a look at a simple example.

Our basic board looks a lot like a classic to-do list but there are two distinct features that set Kanban apart and make it tick; the “In Work” column and its accompanying Work In Progress (WIP) limit. All that you have to know now is that these bits are quite important. What they mean and their place in the system is covered later.

Creating and Using a Kanban Board

Step 1: Create Your Own Board
Go ahead and create your own board. Steal – err – copy the example but of course without the cards. Your board’s construction can be as simple as a set of columns on a sheet of paper or even better, columns on a wall made with tape.

Step 2: Add Items To Your Board
With board construction wrapped up, prime the system by adding items to the “To Do” column. They can come straight from your current to-do list.

Step 3: Start Using It
Select the items that you want to work on and pull them into the “In Work” column. When an item is wrapped up move it on into the “Done” column. Nice, quick, and easy.

But First We Gotta Talk (About Work In Progress Limits)

At this point you may be asking, What prevents me from pulling all of the items over to “In Work”? The answer is, one little but essential thing, the Work In Progress (WIP) limit. On the example board, In Work’s limit is 3. This explicitly means that at any given time only 3 items may be in that column.

Why are WIP limits important?
Coupled with at least one step between To Do and Done, WIP limits help prevent item traffic jams. Think of them working together as a valve for maximizing creative flow.

Who sets the Work In Progress limit?
You do, or in the case of a team environment, the entire team does. The beautiful part is that this number can be tweaked to better fit your workflow. The key is to do so only with careful thought. It should never be done on the fly or on a whim. Here’s why…

Don’t change them on the fly
Ad-hoc manipulation of WIP limits breaks the system. It simply turns the whole thing into extra meaningless work (waste) which is the antithesis of what we want. The voice of experience says to start low and carefully work your way up to a WIP sweet spot. But remember, improvement never stops. So, If at some point in the future a lower limit would make things better then go ahead and make the change.

From flow a myriad of other good things emerge.

Benefits of Kanban

With use, you will find:

  • Improved focus: Because you’re not distracted by the vague sense of how much needs done you can instead hone in on what you’re actually working on.
  • Improved prioritization: Because you are limited to focusing on a few items at a time you develop a keener eye for pulling items that will lead to improved flow.
  • Better risk analysis: Because you actively select items to pull into action you tend to give better thought to what you’re doing and its place within the project. You become freer to analyze and ask questions like, What can prevent this item from being delivered? Can I really hit the deadline?
  • Quicker turnaround times: You tend to complete items in a shorter amount of time because both you and the system become more efficient.
  • More value: Best of all, since you get better at what you do the opportunity presents itself to pack more value into what you’re creating.
  • Everyone on the same page: If you work with others then Kanban can make it easy to share the status of an item. All they have to do is look. This translates into less wasteful communication about status and more about the things that really matter, e.g. impediments, and improvement.

The Essentials of Kanban (How It Works)

You may be wondering why we waited all this time to talk about how Kanban works. Wouldn’t it be easier to know about this stuff ahead of time? Not really. Without seeing and walking through an example these things really don’t mean a whole lot.

The folks over at Crisp.se have done such an incredible job distilling how Kanban works that I’m not even going to try topping it:

  1. Visualize the workflow
    • Split the work into pieces, write each item on a card and put on the wall.
    • Use named columns to illustrate where each item is in the workflow.
  2. Limit WIP (work in progress) – assign explicit limits to how many items may be in progress at each workflow state.
  3. Measure the lead time (average time to complete one item, sometimes called “cycle time”), optimize the process to make lead time as small and predictable as possible.

Whoa, wait? What’s that last thing? Measure the lead time? Is this the first we’ve seen anything about that? No, it’s quicker turnaround times from the Benefits of Kanban section.

Measuring How Long It Takes

The simplest way to get started measuring is to jot the start date on an item when it goes onto your board. When the item is completed mark the finish date right along side. If you really want to get sophisticated then the dates can be entered into a spreadsheet or database. It really depends on your level of technical expertise though it’s probably a good idea to start as low-tech as possible. But no matter how you measure it is an excellent way to:

  • Learn how long it takes to do something.
  • Know how much you are capable of doing in a given period of time.
  • Identify where bottlenecks are in your process.

Wrap-up

Remember, you don’t have to be perfect right out of the gate. The key is to gear yourself for continual improvement. Soon you’ll be beating your own expectations.

In the next article we’ll cover breaking the single “In Work” column out into multiple columns to better reflect a game design specific workflow. The current Firefight! workflow and Kanban board will be used as an example. Read the rest of this entry

The Skinny On Agile Game Design – Part 1

One of my personal projects is the Firefight! Tactical Roleplay Engine. It is a live-action game system designed for use with airsoft. For the most part the project lies outside of the digital domain but the goal is not that different from that of a software project – to deliver a working system.

Non-techie readers, there’s a bunch of vocabulary here but have no fear. I’ve linked terms to definitions.

In The Beginning

Our process revolved around bare bones development iterations. It was pretty simple; we’d develop a chunk of system, write a game event to test that chunk, run the event, hold an informal retrospective and start the next iteration. This approach served us very well in getting the game system off the ground. The first iteration turned out to be an incredibly short 24 hours from initial concept to the first play test event. But since it is a live-action game where you have to organize an event and get people to the same location for testing, iterations tended to be longer than desired. Seasonal weather impacts event scheduling which means that iterations are of irregular length. And of course writing and coordinating events uses large portions of our available time. With these issues in mind we realized that we had to make the most of our development and testing opportunities.

As complexity of the project increased it was becoming ever more difficult for me to manage and communicate progress even though we had a development team of only two people including myself. Most critically, if I was pulled away by an outside force (danged day job!) then the entire project screeched to a halt even if the other developer was available and waiting to work. I was the bottleneck which was completely unacceptable especially considering the size of the team. This had to change.

Enter Agile

I had experience with Agile on software projects so I began pondering how it could be applied to game design. We were already doing a form of Pair Programming where we worked side-by-side to develop and codify ideas. And we were already doing iterative development. We wanted to enhance our adaptability, increase transparency, favor simplicity, and foster unity. These agile values mapped directly to our game design goals.

Initially, we turned to Scrum. It wasn’t a perfect fit but it was a good first step.

The good:

  • Scrum got us thinking about what exactly it was that we were building.
  • Our list of requirements and ad-hoc use cases became user stories that we could better evaluate and revisit.
  • For the first time we were really and truly looking at things from a player’s perspective. This amplified the usefulness of their feedback.
  • Short standup meetings had a positive impact on our motivation. A big problem was that the project could sit idle for periods of time due to burnout. Relying on flashes of inspiration to nudge us back into action is obviously not a good way to get things done. The standup meetings kept us primed and moving.
  • We were no longer just running on gut instinct informed by experience.

The not so good:

  • The reporting components of Scrum didn’t work that well for us. We weren’t able to increase visibility because our burndown chart was wacky because estimation was downright tricky. We simply didn’t have the necessary experience to estimate how long it would take to convert a rule concept into something fit for play. And the velocity chart wasn’t useful because we simply had no idea how to tackle business value during early prototyping.
  • The typical example task board while incredibly useful for visualization wasn’t granular enough to build flashlight metrics for wayfinding. At the time I was so focused on everything Scrum that I couldn’t see how to break the board down into smaller steps.
  • I (acting as ScrumMaster) was still the bottleneck. See next bullet point.
  • I felt overwhelmed far more often than I’d like to admit – like I was juggling too much.

It didn’t take long to figure out that pure Scrum really wasn’t a good fit so we moved on taking with us the bits that worked; bits like time boxing, standup meetings, user stories, and the concept of the task board. We kept moving forward but we soon bogged down a bit from spending too much time examining process. Then things took a lighter turn.

Getting Lean

When I discovered Lean development via the ebook Kanban and Scrum I was thrilled. It was exactly what we were looking for. Kanban in particular immediately jumped to the fore.

Here’s the definition of Kanban at Wikipedia:

Kanban can be divided into two parts:

  • Kanban – A visual process management system that tells what to produce, when to produce it, and how much to produce.
  • The Kanban Method – an approach to incremental, evolutionary process change for organizations.

In our case A visual process management system is a complicated way of saying, “A board with post-it notes stuck to it”. In a future article I’ll cover how we created our Kanban board for game development.

This is the Firefight! Kanban board as of June 2010. It has changed since then.

One tremendous benefit of a Kanban board is that virtually everything is right there for everyone to see at their leisure. This virtually eliminated the management bottleneck. Out of the gate I was doing less management with no sense of juggling.

Other great features include flashlight metric building and process improvement both of which are intrinsic parts of the system. Everyone can see the steps for creating value. And when tackling tasks that you’ve never attempted before you will eventually know exactly how long they take to complete. Building this kind of institutional knowledge is incredibly valuable. A direct benefit is that we are now able to examine both game design itself and the process by which we are creating ours.

Who knew that you could get so much by doing less?

InfoQ: Mobile HTML 5.0

InfoQ: Mobile HTML 5.0.

This is an excellent presentation on HTML 5.0 in the context of mobile applications.

Follow

Get every new post delivered to your Inbox.