of mice and men

My birthday is coming up Novemeber 14th, *wink* *wink*, and the one gift I've been angling for is a Das Keyboard because I like clicky keyboards. Growing up I had a classic IBM Model-M, the original clicky keyboard. I'm not sure why I like the clicky keyboard, it's mostly in my head I'm sure, I feel more productive if I'm making a tremendous amount of noise I guess... maybe that's why I talk so much.

What it comes down to though is feedback. Computers are these amazingly pliable machines, I can play a game of solitaire, balance my checkbook, and write a blog post all on the same machine. It's one of those amazing things that has sadly become commonplace, so much so that we barely think anything about it anymore. This is sad because it's kind of a big deal, take a modern computer back in time 100 years and watch people flip out.

We often think about the User Interface that we see on the screen, but rarely do we consider the Physical Interface that we have with the computer itself, mainly the keyboard and mouse. There is one company though that continues to push the envelope, Apple. Look at their new Magic Mouse, think that chiclet style keyboards are neat, Apple did it first, multitouch you're welcome. This is not an Apple lovefest (all evidence to the contrary), their products work really nicely but that's not the point, they spur others to innovate as well, that's the important part.

So suddenly there is a resurgence in thinking about how we physically interact with computers, look what Microsoft is doing. There is a cornucopia of rumors flying around about a speculative Apple Tablet. And this means really cool interesting gadgets and ideas are now getting the funding to take them from scribbles on a napkin to sketches on a whiteboard to mockup videos to prototypes and then maybe if they hold out to market.

Then I encountered a video a few weeks ago that was so brilliant, so full of potential, that I just wanted to learn as much as possible about it, 10/GUI. Don't take my word for it, check this thing out.

10/GUI from C. Miller on Vimeo.

Pretty neat, huh? There are definitely things some people might not like or want to change, but it is an intriguing idea. With proper funding and research it could turn into something awesome. The problem is that you still have to transition between a 10/GUI touch surface and a keyboard, not a huge deal, but once I saw this my mind was set ablaze with visions of a seamless 10/GUI interface. If you don't want to read that whole page, here is the important part.

The described system in the patent application would individually detect all ten fingers and separate palms on a person's hand, giving the ability to type, write, draw and interact with a device large enough to support multiple hands.
...
Typing is a large part of the lengthy application. The document goes into great detail about how a multi-touch interface could distinguish what keys a set of hands intend to type on the surface. It discusses pressure on the sides or center of individual fingers and palms, and how to interpret those various signals.

The major problem to overcome is feedback, a system that automatically tracks your palms and places the keys under it could allow for touch typing, but as someone who types all day, I don't know if it could work without feedback. This is what they said about the iPhone onscreen soft keyboard, but reports are that people can type anywhere from 40-60 wpm after adjusting.

I'm not sure what the future of the Physical Interface between the user and computer will be, but its definitely an interesting thing to ponder about. Will we have a minority report like 3D interface or a neat 10/GUI pad or the tried and true keyboard and mouse or something that hasn't made it off the scribbled on a napkin phase yet. It sure will be exciting to find out though.

I plan on moving this blog to my own domain over the weekend, but never fear I will keep everyone informed on the move and where you can always get your daily dose of my crazyness

of mice and men

My birthday is coming up Novemeber 14th, *wink* *wink*, and the one gift I've been angling for is a Das Keyboard because I like clicky keyboards. Growing up I had a classic IBM Model-M, the original clicky keyboard. I'm not sure why I like the clicky keyboard, it's mostly in my head I'm sure, I feel more productive if I'm making a tremendous amount of noise I guess... maybe that's why I talk so much.

What it comes down to though is feedback. Computers are these amazingly pliable machines, I can play a game of solitaire, balance my checkbook, and write a blog post all on the same machine. It's one of those amazing things that has sadly become commonplace, so much so that we barely think anything about it anymore. This is sad because it's kind of a big deal, take a modern computer back in time 100 years and watch people flip out.

We often think about the User Interface that we see on the screen, but rarely do we consider the Physical Interface that we have with the computer itself, mainly the keyboard and mouse. There is one company though that continues to push the envelope, Apple. Look at their new Magic Mouse, think that chiclet style keyboards are neat, Apple did it first, multitouch you're welcome. This is not an Apple lovefest (all evidence to the contrary), their products work really nicely but that's not the point, they spur others to innovate as well, that's the important part.

So suddenly there is a resurgence in thinking about how we physically interact with computers, look what Microsoft is doing. There is a cornucopia of rumors flying around about a speculative Apple Tablet. And this means really cool interesting gadgets and ideas are now getting the funding to take them from scribbles on a napkin to sketches on a whiteboard to mockup videos to prototypes and then maybe if they hold out to market.

Then I encountered a video a few weeks ago that was so brilliant, so full of potential, that I just wanted to learn as much as possible about it, 10/GUI. Don't take my word for it, check this thing out.

10/GUI from C. Miller on Vimeo.

Pretty neat, huh? There are definitely things some people might not like or want to change, but it is an intriguing idea. With proper funding and research it could turn into something awesome. The problem is that you still have to transition between a 10/GUI touch surface and a keyboard, not a huge deal, but once I saw this my mind was set ablaze with visions of a seamless 10/GUI interface. If you don't want to read that whole page, here is the important part.

The described system in the patent application would individually detect all ten fingers and separate palms on a person's hand, giving the ability to type, write, draw and interact with a device large enough to support multiple hands.

...
Typing is a large part of the lengthy application. The document goes into great detail about how a multi-touch interface could distinguish what keys a set of hands intend to type on the surface. It discusses pressure on the sides or center of individual fingers and palms, and how to interpret those various signals.

The major problem to overcome is feedback, a system that automatically tracks your palms and places the keys under it could allow for touch typing, but as someone who types all day, I don't know if it could work without feedback. This is what they said about the iPhone onscreen soft keyboard, but reports are that people can type anywhere from 40-60 wpm after adjusting.

I'm not sure what the future of the Physical Interface between the user and computer will be, but its definitely an interesting thing to ponder about. Will we have a minority report like 3D interface or a neat 10/GUI pad or the tried and true keyboard and mouse or something that hasn't made it off the scribbled on a napkin phase yet. It sure will be exciting to find out though.

I plan on moving this blog to my own domain over the weekend, but never fear I will keep everyone informed on the move and where you can always get your daily dose of my crazyness

orm and sql

I've been working on a side project in earnest lately. It's all kinds of PHP fun and I'm enjoying learning the ins and outs of PHP 5.3 as well as relearning some of the stuff I already knew about from my PHP glory days. I've been looking at various different ORM solutions to use with my project and I'd like to take some time to review them, explain why I chose none of them, and what I'm doing instead. For the non-technical in the audience, ORM stands for Object-Relational Mapper, its a piece of software that allows you to save parts of your program to and load them back from a database, supposedly quickly and easily.

• Doctrine
  Doctrine is the 800-pound gorilla of PHP ORM solutions, it has it all, and then some. It is an ORM sitting on top of a DBAL (Database Abstraction Layer) which leverages its own query language DQL (Doctrine Query Language). It can be configured in any number of ways, supports all kinds of backends, is mature, stable, and feature rich. That's all the good of Doctrine, the bad is the learning curve. The manual for Doctrine is 30 sections long, each section is quite a bit to take in. This is great if you are doing an enterprise level program, but for my project Doctrine was overkill.
• Flourish Lib
  This is not an ORM solution, although it does contain one. Flourish is an unframework, and a really, really good one at that. If you want to shut someone up who says you can't write good code in PHP, send them to Flourish, the creator Will Bond did a tremendous job with this unframework, and I still plan on using large parts of it. The ORM layer is actually really nice, there is a bit of a learning curve, and at the end of the day I decided that it did too much and polluted my models too much. Flourish though is definitely worth learning, the website also has great best practices to follow if you are building a PHP Web Application.
• php.activerecord
  Based off of the widely successful Ruby on Rails ActiveRecord class, this project aims to bring the ease of Rails database interactions to PHP. It does not attempt to be a PHP on Rails framework, there are plenty of those, its just a great implementation of the ActiveRecord pattern. The documentation is also fantastic, covering the essentials and letting you jump right in, it feels like there is no learning curve at all.
• RedBean
  This is a complete departure from normal ORM solutions. In a normal solution you are cognizant of both the object model and the relational model, the ORM acts as a pleasant interface for interactions. In RedBean you are freed from having to know about the relational model, in fact you are allowed to let the relational model change on the fly. Need a new attribute for that object, don't worry about migrating schemas, just slap it in there and let RedBean figure out the rest. It is definitely an interesting idea, and it is maturing quickly, but I was wary of using it because of the overly fluid nature and the business constraints of my project

Those are the most interesting ones I investigated, I investigated quite a few other ones, but these were definitely the cream of the crop. None of them fit my project, but my project is a little bit weird (if you keep reading this blog you will no doubt see it one day, unless something shiny grabs my attention and I wonder off). If you are looking for a really powerful ORM with all the bells and whistles, check out Doctrine. If you are familiar with ActiveRecord, php.activerecord is a fantastic implementation. If you are programming PHP at all, take the time to read through Will Bond's amazing Flourish Lib. If you need some lightweight persistence or want to dabble in some object-oriented databases, give RedBean a try. Really on that last one, if you are even at all interested by technology, check out RedBean, it is a little young but shows amazing potential and is a great example of thinking outside the box.

So what did I decide, well I decided I don't want to use an ORM layer. ORM didn't fit my use case, I was only experiencing developer pain trying to shoehorn it in there. I decided that what I needed was something a little different, and I'm currently developing exactly that. So what is this mystery project that I'm working on, its a couple different parts that work together, but I decided that all I really wanted was the following list of things.

• Cross platform SQL
• Automatic CRUD
• Lightweight library

So I'm writing them, and I will be releasing at least part of it soon, once I get it to a point where it does something, then expect a blog post with trumpets and whatnot. I conceived the project structure last night and began coding, I was able to put in 3 hours of work and got a very nice proof of concept running, but it is still all sharp edges and scuffed surfaces.

Stay tuned though, I hope to have something people can put their fingers on soon. I think there is a need for the lightweight components that I'm building, as a platform for future innovation and because after 3 months of looking around I couldn't find anything out there that did what I needed.

orm and sql

I've been working on a side project in earnest lately. It's all kinds of PHP fun and I'm enjoying learning the ins and outs of PHP 5.3 as well as relearning some of the stuff I already knew about from my PHP glory days. I've been looking at various different ORM solutions to use with my project and I'd like to take some time to review them, explain why I chose none of them, and what I'm doing instead. For the non-technical in the audience, ORM stands for Object-Relational Mapper, its a piece of software that allows you to save parts of your program to and load them back from a database, supposedly quickly and easily.

• Doctrine
  Doctrine is the 800-pound gorilla of PHP ORM solutions, it has it all, and then some. It is an ORM sitting on top of a DBAL (Database Abstraction Layer) which leverages its own query language DQL (Doctrine Query Language). It can be configured in any number of ways, supports all kinds of backends, is mature, stable, and feature rich. That's all the good of Doctrine, the bad is the learning curve. The manual for Doctrine is 30 sections long, each section is quite a bit to take in. This is great if you are doing an enterprise level program, but for my project Doctrine was overkill.


• Flourish Lib
  This is not an ORM solution, although it does contain one. Flourish is an unframework, and a really, really good one at that. If you want to shut someone up who says you can't write good code in PHP, send them to Flourish, the creator Will Bond did a tremendous job with this unframework, and I still plan on using large parts of it. The ORM layer is actually really nice, there is a bit of a learning curve, and at the end of the day I decided that it did too much and polluted my models too much. Flourish though is definitely worth learning, the website also has great best practices to follow if you are building a PHP Web Application.


• php.activerecord
  Based off of the widely successful Ruby on Rails ActiveRecord class, this project aims to bring the ease of Rails database interactions to PHP. It does not attempt to be a PHP on Rails framework, there are plenty of those, its just a great implementation of the ActiveRecord pattern. The documentation is also fantastic, covering the essentials and letting you jump right in, it feels like there is no learning curve at all.


• RedBean
  This is a complete departure from normal ORM solutions. In a normal solution you are cognizant of both the object model and the relational model, the ORM acts as a pleasant interface for interactions. In RedBean you are freed from having to know about the relational model, in fact you are allowed to let the relational model change on the fly. Need a new attribute for that object, don't worry about migrating schemas, just slap it in there and let RedBean figure out the rest. It is definitely an interesting idea, and it is maturing quickly, but I was wary of using it because of the overly fluid nature and the business constraints of my project

Those are the most interesting ones I investigated, I investigated quite a few other ones, but these were definitely the cream of the crop. None of them fit my project, but my project is a little bit weird (if you keep reading this blog you will no doubt see it one day, unless something shiny grabs my attention and I wonder off). If you are looking for a really powerful ORM with all the bells and whistles, check out Doctrine. If you are familiar with ActiveRecord, php.activerecord is a fantastic implementation. If you are programming PHP at all, take the time to read through Will Bond's amazing Flourish Lib. If you need some lightweight persistence or want to dabble in some object-oriented databases, give RedBean a try. Really on that last one, if you are even at all interested by technology, check out RedBean, it is a little young but shows amazing potential and is a great example of thinking outside the box.

So what did I decide, well I decided I don't want to use an ORM layer. ORM didn't fit my use case, I was only experiencing developer pain trying to shoehorn it in there. I decided that what I needed was something a little different, and I'm currently developing exactly that. So what is this mystery project that I'm working on, its a couple different parts that work together, but I decided that all I really wanted was the following list of things.

• Cross platform SQL


• Automatic CRUD


• Lightweight library

So I'm writing them, and I will be releasing at least part of it soon, once I get it to a point where it does something, then expect a blog post with trumpets and whatnot. I conceived the project structure last night and began coding, I was able to put in 3 hours of work and got a very nice proof of concept running, but it is still all sharp edges and scuffed surfaces.

Stay tuned though, I hope to have something people can put their fingers on soon. I think there is a need for the lightweight components that I'm building, as a platform for future innovation and because after 3 months of looking around I couldn't find anything out there that did what I needed.

related tasks

I remember watching Mitch Hedburg one time talk about how comedy is an odd kind of profession because if you are really good at it you have to stop doing it. The point he was making is that if you are successful enough at stand-up then one day people are going to ask you if you can act and write and star in movies. Here is the pertinent quote.

When you’re in Hollywood and you’re a comedian, everybody wants you to do other things that are related to comedy, but are not stand-up comedy. ‘All right, you’re a stand-up comedian, can you write us a script?’ That’s not fair. That’s like if I worked hard all my life to become a really good chef, they’d say, ‘OK, you’re a chef. Can you farm?’

This is a less severe version of the Peter Principle.

But it's not just comedians, Software Development has a whole host of secondary tasks that are related, sometimes closely, sometimes not so closely, that need to be taken care of. I've found myself in a secondary task day the last few days.

• New client conference call
• Functional Specification examination and inquiry
• Task list creation and time estimates
• Talking to a hosting company about plan upgrades
• Researching a fix for PCI non-compliance issue
• Researching why in the hell IIS6 wouldn't serve .aspx pages (Web Service Extension wasn't permitted)
• Fighting with a dev environment to get an application running to test whether or not a PCI Compliance fix would break the application
• Taking a break from fighting with the maddening server to write a blog post

These secondary tasks are all necessary, some are enjoyable (blogging), some I'm surprisingly skilled at (research, talking), some make me feel completely out of my element (time estimates, server configuration). In the landmark The Law of Leaky Abstractions and the follow up The Development Abstraction, Joel writes

Any successful software company is going to consist of a thin layer of developers, creating software, spread across the top of a big abstract administrative organization. The abstraction exists solely to create the illusion that the daily activities of a programmer (design and writing code, checking in code, debugging, etc.) are all that it takes to create software products and bring them to market.

Its not that I don't want to perform these secondary tasks, or that I'm not good at them, it's just that I'm much more productive at coding. My brain is set up for it, ask anyone that knows me, I think about life as one big program, I examine my emotions based off of function arguments, I turn situations into class hierarchies, it's just how my brain works. Programming makes sense to me, I feel at home there, I feel warm and cuddly wrapped in curly braces, and I work really well there.

These secondary tasks, related tasks, need to get done, and because of my availability I'm the one to do them. It's good to learn new things, but also scary and uncomfortable and frustrating.

I don't know if there is a point to writing this, it started off as a rant against feeling forced to waste my time and skills on tasks that I don't feel comfortable doing, but it hasn't ended there. It hasn't really ended anywhere, it's a reality, so I'll deal.

All I know is that right now the abstraction is leaking and getting my clothes wet, I long to wrap myself in comfy curly braces by a warm fire and feel like I know what I'm doing again.

related tasks

I remember watching Mitch Hedburg one time talk about how comedy is an odd kind of profession because if you are really good at it you have to stop doing it. The point he was making is that if you are successful enough at stand-up then one day people are going to ask you if you can act and write and star in movies. Here is the pertinent quote.

When you’re in Hollywood and you’re a comedian, everybody wants you to do other things that are related to comedy, but are not stand-up comedy. ‘All right, you’re a stand-up comedian, can you write us a script?’ That’s not fair. That’s like if I worked hard all my life to become a really good chef, they’d say, ‘OK, you’re a chef. Can you farm?’

This is a less severe version of the Peter Principle.

But it's not just comedians, Software Development has a whole host of secondary tasks that are related, sometimes closely, sometimes not so closely, that need to be taken care of. I've found myself in a secondary task day the last few days.

• New client conference call


• Functional Specification examination and inquiry


• Task list creation and time estimates


• Talking to a hosting company about plan upgrades


• Researching a fix for PCI non-compliance issue


• Researching why in the hell IIS6 wouldn't serve .aspx pages (Web Service Extension wasn't permitted)


• Fighting with a dev environment to get an application running to test whether or not a PCI Compliance fix would break the application


• Taking a break from fighting with the maddening server to write a blog post

These secondary tasks are all necessary, some are enjoyable (blogging), some I'm surprisingly skilled at (research, talking), some make me feel completely out of my element (time estimates, server configuration). In the landmark The Law of Leaky Abstractions and the follow up The Development Abstraction, Joel writes

Any successful software company is going to consist of a thin layer of developers, creating software, spread across the top of a big abstract administrative organization.

The abstraction exists solely to create the illusion that the daily activities of a programmer (design and writing code, checking in code, debugging, etc.) are all that it takes to create software products and bring them to market.

Its not that I don't want to perform these secondary tasks, or that I'm not good at them, it's just that I'm much more productive at coding. My brain is set up for it, ask anyone that knows me, I think about life as one big program, I examine my emotions based off of function arguments, I turn situations into class hierarchies, it's just how my brain works. Programming makes sense to me, I feel at home there, I feel warm and cuddly wrapped in curly braces, and I work really well there.

These secondary tasks, related tasks, need to get done, and because of my availability I'm the one to do them. It's good to learn new things, but also scary and uncomfortable and frustrating.

I don't know if there is a point to writing this, it started off as a rant against feeling forced to waste my time and skills on tasks that I don't feel comfortable doing, but it hasn't ended there. It hasn't really ended anywhere, it's a reality, so I'll deal.

All I know is that right now the abstraction is leaking and getting my clothes wet, I long to wrap myself in comfy curly braces by a warm fire and feel like I know what I'm doing again.

installation

Today at work I had the joyful experience of installing WordPress on my development machine. My 9-5 is working in the .Net arena so my machine is set up with IIS 7, MSSQL 2008, Visual Studio 2008, a cutting edge Microsoft stack. So when I was told to install WordPress to do some testing, I knew I would have to install a LAMP stack (minus the L) and then the WordPress software, I prepared myself to do battle.

Actually I had the feeling that this would be pretty easy, I use to work in LAMP and MAMP and WAMP stacks all day long so I could at least skip over the, "how the hell do I start?" phase and jump in head first.

I headed over to XAMPP and grabbed the latest Windows installer. 44 megabytes later I double clicked, selected my destination directory, C:\ (XAMPP automatically makes a folder called xampp to put itself in, I've made this mistake more than once and ended up with my install in C:\xampp\xampp), and clicked install. It churned and churned and I took the opportunity to grab a Diet Dr. Pepper. 5 minutes later I had a fully functional WAMP machine at my fingertips.

I double-clicked the XAMPP Control Panel icon and fired up Apache and MySql, clicked the Admin button and was whisked away to http://localhost/. After some security configuration, clicked security, entered a password, simple enough, I turned my sights on WordPress.

I pointed my web browser at the WordPress Download Page grabbed the zip and clicked through to the handy guide

The handy guide lived up to its name, especially the Famous 5-Minute Install.

In about 15 minutes I was able to painlessly install Apache, MySQL, PHP, Perl, and WordPress. It cost me nothing, and it all just seamlessly worked. In short it was the model install experience.

Installation can be easy to overlook, you write your app coding and coding away and you never think about getting it set-up. What often makes it worse is that as programmers we normally don't think much of complicated tasks or dialogs that would scare the average user. Installation is your software's first impression, and you know what they say about first impressions, try not to be a jackass.

When installations work right you should feel more and more comfortable as you follow the steps, WordPress is a great example. Every step I could see more and more of WordPress shining through, it didn't just work, it was intuitive and actually made me want to use it. Every step assured me that I had done the right thing and helpfully pointed me to the most important things to know for the next step. There was no technical jargon, just do exactly this, type here, click here, enjoy! It was short, simple, and sublime.

So in this world of web applications where we no longer think about installation, if you are going to make your end-user install something, make sure that you do the following

• Provide plenty of up-to-date documentation
• Make the process as simple as possible
• Provide feedback, both positive and negative
• Centralize your installation process

Follow this advice and someday someone will write a blog post about how much of a joy it was to install your software.

installation

Today at work I had the joyful experience of installing WordPress on my development machine. My 9-5 is working in the .Net arena so my machine is set up with IIS 7, MSSQL 2008, Visual Studio 2008, a cutting edge Microsoft stack. So when I was told to install WordPress to do some testing, I knew I would have to install a LAMP stack (minus the L) and then the WordPress software, I prepared myself to do battle.

Actually I had the feeling that this would be pretty easy, I use to work in LAMP and MAMP and WAMP stacks all day long so I could at least skip over the, "how the hell do I start?" phase and jump in head first.

I headed over to XAMPP and grabbed the latest Windows installer. 44 megabytes later I double clicked, selected my destination directory, C:\ (XAMPP automatically makes a folder called xampp to put itself in, I've made this mistake more than once and ended up with my install in C:\xampp\xampp), and clicked install. It churned and churned and I took the opportunity to grab a Diet Dr. Pepper. 5 minutes later I had a fully functional WAMP machine at my fingertips.

I double-clicked the XAMPP Control Panel icon and fired up Apache and MySql, clicked the Admin button and was whisked away to http://localhost/. After some security configuration, clicked security, entered a password, simple enough, I turned my sights on WordPress.

I pointed my web browser at the WordPress Download Page grabbed the zip and clicked through to the handy guide

The handy guide lived up to its name, especially the Famous 5-Minute Install.

In about 15 minutes I was able to painlessly install Apache, MySQL, PHP, Perl, and WordPress. It cost me nothing, and it all just seamlessly worked. In short it was the model install experience.

Installation can be easy to overlook, you write your app coding and coding away and you never think about getting it set-up. What often makes it worse is that as programmers we normally don't think much of complicated tasks or dialogs that would scare the average user. Installation is your software's first impression, and you know what they say about first impressions, try not to be a jackass.

When installations work right you should feel more and more comfortable as you follow the steps, WordPress is a great example. Every step I could see more and more of WordPress shining through, it didn't just work, it was intuitive and actually made me want to use it. Every step assured me that I had done the right thing and helpfully pointed me to the most important things to know for the next step. There was no technical jargon, just do exactly this, type here, click here, enjoy! It was short, simple, and sublime.

So in this world of web applications where we no longer think about installation, if you are going to make your end-user install something, make sure that you do the following

• Provide plenty of up-to-date documentation


• Make the process as simple as possible


• Provide feedback, both positive and negative


• Centralize your installation process

Follow this advice and someday someone will write a blog post about how much of a joy it was to install your software.

motion controls and ai

I was talking with a friend today about dj hero (which comes out later today) and he asked a simple question, "Have you heard anything about the next wave of game systems?" I read all kinds of electronics blogs like Gizmodo, Engadget, and even Hacker News and haven't seen anything about a PS4 or a Xbox720.

The PS3 was released on November 17, 2006, the Xbox 360 on May 12, 2005. So we are looking at about 3 or 4 years since the last generation, considering that the PS2 and original Xbox launched in 2000 and 2001, respectively, means that we may not see anything for a little while longer. But the weird thing is that there is no chatter, no rumors about the next-gen consoles, and I got to wondering why.

You may have noticed above that I left someone out, Nintendo's Wii. Hold on, don't get your Mario shaped pitch-forks out yet, I would argue that the Wii is what is causing the current drought in next-gen systems. The old logic of producing a next-gen system was as follows

1. Release system
2. Make giant profits
3. Wait for Moore's law to create more powerful hardware
4. Put more powerful hardware in box
5. Increment number after system name
6. Brag about polygon count
7. Goto step 1

The problem is 2 fold though. The first problem is that we are approaching the uncanny valley, possible even stuck in it. Have you seen the games little kids get to play these days, they are gorgeous, expansive, photo-realistic dream worlds. Let's compare and contrast

Super Mario (NES)

Gears of War (Xbox 360)

Need for Speed: Carbon (PS3)

Pumping out more polygons isn't really an issue anymore, we have reached the land of diminishing returns. So the idea of just putting out a more powerful machine isn't really going to get most people off of the couches and out in the stores.

The second issue is that Nintendo totally messed everything up, they put out a system that was just about the same power, had some weird remote control thing, and they DOMINATED the market. This decimated the conventional wisdom, you can't put something out that isn't more powerful and have people buy it, what's happening!?!? This can't be happening, deep breaths everyone, Bill Gates just threw up. The news talked about it nonstop, people were selling Wiis for a ton on ebay, the holiday season saw more than its fair share of customers fighting, waiting, and pleading for the hottest new video game system, the Wii. And its actually pretty fun, I've played Wii Sports Resort with my brother for hours on end, kicking his ass at frisbee golf.

Immediately though, people had to know, what is the secret sauce of their success, it must be that goofy remote. Sony quickly tried to slap some motion sensing into their sixaxis controller, with terrible results. Well now both big players have gone back to the drawing board to make some motion sensing controls.

Microsoft's Project Natal

Sony's motion sensing wand thing

Everyone has decided that motion controls are going to be a big part of the future of gaming. The problem is that motion controls have inherent flaws that all the sensitivity and one to one motion sensing in the world can't fix. Motion controls fail in 2 important ways, the first is that motion controls only make sense for certain activities, bowling, frisbee, sword play, gun fights, all can be done nicely with motion controls. But have you ever played a Wii game where the motion controls are tacked on (95%) or confusing (90%) or annoying (90%) or the wiimote is turned into a glorified mouse pointer. If not then you have never played anything but the AAA titles, and that's fine, that's why we have AAA titles, because they are good. They represent a tiny fraction of all games on the Wii though, the vast majority of what's out there was pumped out to cash in on a phenomenon, with motion controls thrown in for good measure, and normally to the detriment of the game.

The prime example in my mind is the Ghostbuster Wii port, a serviceable enough game, but the annoying swinging and shaking and quick-time event motion controls for every single ghost get annoying and unnecessary.

The second problem is that motion controls is a concept that is at odds against itself. On one hand your body is supposed to become an extension of the controller, you should be able to blur the line (in your mind's eye) between your actions in real life and the actions on the screen. The problem is that there is no force feedback, when your sword blow is parried by a wily electronic foe, your arms keeps going but the character's arm on the screen stops. There is no resistance as you shop through a tree, there is no physical feedback for the motion you are making. The fantasy world where you are the brave knight bravely trying to rescue the beautiful princess comes crashing down around you when you and your characters movements become out of sync, and suddenly you are back in your living room in your sweatpants swinging a remote like a jackass.

The Wii was successful because they marketed their machine to the casual gamer, this great untapped resource, and they had a great novelty to get their foot in the door. And it worked, and I will admit that the well made games on the Wii are a hell of a lot of fun, and I do enjoy the little system that could. The point of this post is not to rag on the Wii but to say that it succeeded in spite of the wiimote not because of it, and the new adventure down motion control road will end up being a blind alley.

So where does this leave us, what is the future of gaming? I don't know for certain, but I will finish up with what I would like to see. Improvements in Artificial Intelligence. Artificial Intelligence's capabilities were over promised and underwhelming, this has led to AI Winter. Most people today think that there is something fundamental about AI that it could never work, that the best we can make is not very good at all. And that really is the state of most AI today, especially game AI. When was the last time the game gave you AI teammates and you thought to yourself, "Yea, AI Teammates!" instead of "I wonder if I will lose points for murdering them." Not very often I bet, because AI is horrible, its even worse when its trying to help you. If Sony and Microsoft spent some serious money on developing an AI framework for their developers to use, they could make the games much more fun.

How do I know it would be more fun, look at the rise of MMORPGs. Massively Multiplayer games are fun because your opponents and teammates are smart enough to make the gameplay more enjoyable. MMOs also suffer from various policing issues and behavior, anyone who has been called a n00b by a thirteen year old after he's headshot and teabagged you knows that the fun often comes at the price of dealing with the worst of human behavior. Its not always so bad, and after a while you learn the rules of the world and online gameplay can be great fun, that's why its a major part of almost any AAA title released these days.

Its this drive to have intelligent opponents that don't feel like they are cheating, teammates who can understand strategy and don't need to be micromanaged, and gameplay that is both rich and engaging that has brought MMOs, Xbox Live, and PSN to the forefront. The software AI has failed so we went back to using people, which is great, video game nerds need as much socializing as possible. But if a little injection of intelligence can be fun, much more intelligence can (and I stress can, not will, it could end up horrible) be much more fun. I think this is where the future of gaming lies, not in various wands and cameras.

This post got long and out of control, also it was fairly off topic, I hope to be back on programming tomorrow

motion controls and ai

I was talking with a friend today about dj hero (which comes out later today) and he asked a simple question, "Have you heard anything about the next wave of game systems?" I read all kinds of electronics blogs like Gizmodo, Engadget, and even Hacker News and haven't seen anything about a PS4 or a Xbox720.

The PS3 was released on November 17, 2006, the Xbox 360 on May 12, 2005. So we are looking at about 3 or 4 years since the last generation, considering that the PS2 and original Xbox launched in 2000 and 2001, respectively, means that we may not see anything for a little while longer. But the weird thing is that there is no chatter, no rumors about the next-gen consoles, and I got to wondering why.

You may have noticed above that I left someone out, Nintendo's Wii. Hold on, don't get your Mario shaped pitch-forks out yet, I would argue that the Wii is what is causing the current drought in next-gen systems. The old logic of producing a next-gen system was as follows

1. Release system


2. Make giant profits


3. Wait for Moore's law to create more powerful hardware


4. Put more powerful hardware in box


5. Increment number after system name


6. Brag about polygon count


7. Goto step 1

The problem is 2 fold though. The first problem is that we are approaching the uncanny valley, possible even stuck in it. Have you seen the games little kids get to play these days, they are gorgeous, expansive, photo-realistic dream worlds. Let's compare and contrast

Super Mario (NES)

Gears of War (Xbox 360)

Need for Speed: Carbon (PS3)

Pumping out more polygons isn't really an issue anymore, we have reached the land of diminishing returns. So the idea of just putting out a more powerful machine isn't really going to get most people off of the couches and out in the stores.

The second issue is that Nintendo totally messed everything up, they put out a system that was just about the same power, had some weird remote control thing, and they DOMINATED the market. This decimated the conventional wisdom, you can't put something out that isn't more powerful and have people buy it, what's happening!?!? This can't be happening, deep breaths everyone, Bill Gates just threw up. The news talked about it nonstop, people were selling Wiis for a ton on ebay, the holiday season saw more than its fair share of customers fighting, waiting, and pleading for the hottest new video game system, the Wii. And its actually pretty fun, I've played Wii Sports Resort with my brother for hours on end, kicking his ass at frisbee golf.

Immediately though, people had to know, what is the secret sauce of their success, it must be that goofy remote. Sony quickly tried to slap some motion sensing into their sixaxis controller, with terrible results. Well now both big players have gone back to the drawing board to make some motion sensing controls.

Microsoft's Project Natal

Sony's motion sensing wand thing

Everyone has decided that motion controls are going to be a big part of the future of gaming. The problem is that motion controls have inherent flaws that all the sensitivity and one to one motion sensing in the world can't fix. Motion controls fail in 2 important ways, the first is that motion controls only make sense for certain activities, bowling, frisbee, sword play, gun fights, all can be done nicely with motion controls. But have you ever played a Wii game where the motion controls are tacked on (95%) or confusing (90%) or annoying (90%) or the wiimote is turned into a glorified mouse pointer. If not then you have never played anything but the AAA titles, and that's fine, that's why we have AAA titles, because they are good. They represent a tiny fraction of all games on the Wii though, the vast majority of what's out there was pumped out to cash in on a phenomenon, with motion controls thrown in for good measure, and normally to the detriment of the game.

The prime example in my mind is the Ghostbuster Wii port, a serviceable enough game, but the annoying swinging and shaking and quick-time event motion controls for every single ghost get annoying and unnecessary.

The second problem is that motion controls is a concept that is at odds against itself. On one hand your body is supposed to become an extension of the controller, you should be able to blur the line (in your mind's eye) between your actions in real life and the actions on the screen. The problem is that there is no force feedback, when your sword blow is parried by a wily electronic foe, your arms keeps going but the character's arm on the screen stops. There is no resistance as you shop through a tree, there is no physical feedback for the motion you are making. The fantasy world where you are the brave knight bravely trying to rescue the beautiful princess comes crashing down around you when you and your characters movements become out of sync, and suddenly you are back in your living room in your sweatpants swinging a remote like a jackass.

The Wii was successful because they marketed their machine to the casual gamer, this great untapped resource, and they had a great novelty to get their foot in the door. And it worked, and I will admit that the well made games on the Wii are a hell of a lot of fun, and I do enjoy the little system that could. The point of this post is not to rag on the Wii but to say that it succeeded in spite of the wiimote not because of it, and the new adventure down motion control road will end up being a blind alley.

So where does this leave us, what is the future of gaming? I don't know for certain, but I will finish up with what I would like to see. Improvements in Artificial Intelligence. Artificial Intelligence's capabilities were over promised and underwhelming, this has led to AI Winter. Most people today think that there is something fundamental about AI that it could never work, that the best we can make is not very good at all. And that really is the state of most AI today, especially game AI. When was the last time the game gave you AI teammates and you thought to yourself, "Yea, AI Teammates!" instead of "I wonder if I will lose points for murdering them." Not very often I bet, because AI is horrible, its even worse when its trying to help you. If Sony and Microsoft spent some serious money on developing an AI framework for their developers to use, they could make the games much more fun.

How do I know it would be more fun, look at the rise of MMORPGs. Massively Multiplayer games are fun because your opponents and teammates are smart enough to make the gameplay more enjoyable. MMOs also suffer from various policing issues and behavior, anyone who has been called a n00b by a thirteen year old after he's headshot and teabagged you knows that the fun often comes at the price of dealing with the worst of human behavior. Its not always so bad, and after a while you learn the rules of the world and online gameplay can be great fun, that's why its a major part of almost any AAA title released these days.

Its this drive to have intelligent opponents that don't feel like they are cheating, teammates who can understand strategy and don't need to be micromanaged, and gameplay that is both rich and engaging that has brought MMOs, Xbox Live, and PSN to the forefront. The software AI has failed so we went back to using people, which is great, video game nerds need as much socializing as possible. But if a little injection of intelligence can be fun, much more intelligence can (and I stress can, not will, it could end up horrible) be much more fun. I think this is where the future of gaming lies, not in various wands and cameras.

This post got long and out of control, also it was fairly off topic, I hope to be back on programming tomorrow

treasure hunting

Working with programming languages is fun stuff. If you are a programmer then you probably only think about your language as much as you need to to get the job done. In fact you have to really, if you spent all day thinking about how the compiler is going to allocate this variable off the stack or this one off the heap or how its going to write out the virtual lookup tables, you could never get anything accomplished.

It's a shame though because our programming languages are some of the most interesting and complex software we interact with. If you are willing to look around you can find some real treasures out there, and even if you never code anything of importance in these new found treasures, the experience will pay dividends elsewhere.

I'd like to take you on a tour of the treasures I've found in my travels through the world we call programming, I'll split it into four easy to consume chunks.

The Past

The history of our field is short, still short enough that you can probably come to know most if not all of it. This is one of the interesting things about Computer Science, its a field that, in it's modern form, is about 60 years old. The amazing thing about all this is that there are some gems from the past, truly ground breaking work that we still use today.

• Lisp
  As you may well be aware I've recently fallen in love with lisp, I'm starting to think about her all the time, and you can too. The amazing thing that, to this moment, knocks my socks off, is that Lisp was originally conceived in 1958 and has all kinds of concepts that you wouldn't expect from a language in it's 50s. Closures, homoiconic code, anonymous functions, object oriented programming, and a web framework. There is a lot more to this language, and it is definitely worth your time, go read up.
• Smalltalk
  This one comes from the 1970's from the famous Xerox PARC. Smalltalk was way ahead of its time with a fully integrated development environment, a fully functional GUI, no files (this sounds bad at first, but its freeing not having to worry about where your source lives), everything is a file, and much more. Smalltalk's influence is far reaching even to this day, Objective-C borrows heavily from it, and the influential Gang of Four book offers source in C++ and Smalltalk.
• C
  Hard to believe that this staple of computer programming was invented in 1972. Without C, Unix would not exist. C is still crazy fast, basically human readable assembly, and still widely used. The backbone and infrastructure of most of our technology exists because of C. Have a scripting language, need a way to shut people up who are saying it's too slow, allow them to call C modules, done. C is definitely worth knowing, you can access a giant pile of source code, and get as close to the machine as possible without busting out the x86 Assembly Guide.

The Present

• Ruby
  This is the current hotness, although its hotness may be waning somewhat. Today ruby is the top language on github and there is a new interesting project written in ruby everyday. Ruby on Rails created the rockstar ruby programmer, and revolutionized data backed web development. Ruby is going to be around for a while, and because of REPL its easy to get started.
• JVM Languages
  Java may be out, but the virtual maching that runs the language has never been more popular. Clojure (a JVM Lisp, which will probably get its own article soon) and Scala are up and coming. The ubiquity of the JVM means that you can run this code on almost any machine, and the languages are squeezing speed and performance out of the JVM that would have been unheard of a few years ago. These languages can also leverage the huge pile of Java Libraries out in the wild, so the first major hurdle to a new language (what can this thing actually do and are there any tools for it), is easily leapt.
• DSLs
  Domain Specific Languages are starting to come into their own. Some of this popularity is owed to the rise of ruby which makes writing a new DSL somewhat trivial. Sass, Haml, and many others DSLs are beginning to find more and more adoption within their domain.

The Future

• Functional Programming
  Erlang, Haskell, OCaml, etc. are beginning to see an upswing in interest. The rise of multi-processor cores and the inherent complexity of mutli-threaded programming in imperative programming makes these languages a tantalizing option. Erlang can support millions of threads with simple, easy to understand code. CouchDB will be the proving ground for Erlang's efficacy.
• JavaScript
  As I wrote in the future: javascript

  When it get's down to it, JavaScript is a great language. It has a ton of exposure, and a huge amount of developer mindshare. JavaScript isn't going away anytime soon, and considering how hard it is to get browser vendor's to agree, isn't getting replaced anytime soon. JavaScript will become more and more prevalent both on the server and on the desktop. I welcome our new prototype based overlord, and so should you.

  So far nothing has changed.
• Anything
  That is one of the most exciting things about this field, it could be anything. Before Ruby on Rails, the ruby language was a small odd scripting language that few outside of Japan had heard about. With the success of RoR ruby (which is an acceptable lisp) use has exploded and they have gained massive developer mindshare. Tomorrow a new technology could set the world ablaze, and the best part is that we have a chance to shape that future. This is an industry in which a man with a great idea can truly change the face of the development landscape.

These are just some of the treasures I have discovered by opening my eyes and looking around. There are plenty more gems that I have found that didn't make it into this post, but only because these one's were on the top of my brain. If you encounter a new language, take an hour or so to run through a tutorial, it could be worth it, it might not. You may find yourself falling in love, or maybe you missed a few episodes of the Simpsons. At the end of the day though, you will be glad that you took the time to learn something new, when you see glimmers of it in something old, and your knowledge of share-nothing concurrency saves the day on your next project.

This is a dynamic wonderful field, go play!

treasure hunting

Working with programming languages is fun stuff. If you are a programmer then you probably only think about your language as much as you need to to get the job done. In fact you have to really, if you spent all day thinking about how the compiler is going to allocate this variable off the stack or this one off the heap or how its going to write out the virtual lookup tables, you could never get anything accomplished.

It's a shame though because our programming languages are some of the most interesting and complex software we interact with. If you are willing to look around you can find some real treasures out there, and even if you never code anything of importance in these new found treasures, the experience will pay dividends elsewhere.

I'd like to take you on a tour of the treasures I've found in my travels through the world we call programming, I'll split it into four easy to consume chunks.

The Past

The history of our field is short, still short enough that you can probably come to know most if not all of it. This is one of the interesting things about Computer Science, its a field that, in it's modern form, is about 60 years old. The amazing thing about all this is that there are some gems from the past, truly ground breaking work that we still use today.

• Lisp
  As you may well be aware I've recently fallen in love with lisp, I'm starting to think about her all the time, and you can too. The amazing thing that, to this moment, knocks my socks off, is that Lisp was originally conceived in 1958 and has all kinds of concepts that you wouldn't expect from a language in it's 50s. Closures, homoiconic code, anonymous functions, object oriented programming, and a web framework. There is a lot more to this language, and it is definitely worth your time, go read up.


• Smalltalk
  This one comes from the 1970's from the famous Xerox PARC. Smalltalk was way ahead of its time with a fully integrated development environment, a fully functional GUI, no files (this sounds bad at first, but its freeing not having to worry about where your source lives), everything is a file, and much more. Smalltalk's influence is far reaching even to this day, Objective-C borrows heavily from it, and the influential Gang of Four book offers source in C++ and Smalltalk.


• C
  Hard to believe that this staple of computer programming was invented in 1972. Without C, Unix would not exist. C is still crazy fast, basically human readable assembly, and still widely used. The backbone and infrastructure of most of our technology exists because of C. Have a scripting language, need a way to shut people up who are saying it's too slow, allow them to call C modules, done. C is definitely worth knowing, you can access a giant pile of source code, and get as close to the machine as possible without busting out the x86 Assembly Guide.

The Present

• Ruby
  This is the current hotness, although its hotness may be waning somewhat. Today ruby is the top language on github and there is a new interesting project written in ruby everyday. Ruby on Rails created the rockstar ruby programmer, and revolutionized data backed web development. Ruby is going to be around for a while, and because of REPL its easy to get started.


• JVM Languages
  Java may be out, but the virtual maching that runs the language has never been more popular. Clojure (a JVM Lisp, which will probably get its own article soon) and Scala are up and coming. The ubiquity of the JVM means that you can run this code on almost any machine, and the languages are squeezing speed and performance out of the JVM that would have been unheard of a few years ago. These languages can also leverage the huge pile of Java Libraries out in the wild, so the first major hurdle to a new language (what can this thing actually do and are there any tools for it), is easily leapt.


• DSLs
  Domain Specific Languages are starting to come into their own. Some of this popularity is owed to the rise of ruby which makes writing a new DSL somewhat trivial. Sass, Haml, and many others DSLs are beginning to find more and more adoption within their domain.

The Future

• Functional Programming
  Erlang, Haskell, OCaml, etc. are beginning to see an upswing in interest. The rise of multi-processor cores and the inherent complexity of mutli-threaded programming in imperative programming makes these languages a tantalizing option. Erlang can support millions of threads with simple, easy to understand code. CouchDB will be the proving ground for Erlang's efficacy.


• JavaScript
  As I wrote in the future: javascript

  When it get's down to it, JavaScript is a great language. It has a ton of exposure, and a huge amount of developer mindshare. JavaScript isn't going away anytime soon, and considering how hard it is to get browser vendor's to agree, isn't getting replaced anytime soon. JavaScript will become more and more prevalent both on the server and on the desktop. I welcome our new prototype based overlord, and so should you.

  So far nothing has changed.


• Anything
  That is one of the most exciting things about this field, it could be anything. Before Ruby on Rails, the ruby language was a small odd scripting language that few outside of Japan had heard about. With the success of RoR ruby (which is an acceptable lisp) use has exploded and they have gained massive developer mindshare. Tomorrow a new technology could set the world ablaze, and the best part is that we have a chance to shape that future. This is an industry in which a man with a great idea can truly change the face of the development landscape.

These are just some of the treasures I have discovered by opening my eyes and looking around. There are plenty more gems that I have found that didn't make it into this post, but only because these one's were on the top of my brain. If you encounter a new language, take an hour or so to run through a tutorial, it could be worth it, it might not. You may find yourself falling in love, or maybe you missed a few episodes of the Simpsons. At the end of the day though, you will be glad that you took the time to learn something new, when you see glimmers of it in something old, and your knowledge of share-nothing concurrency saves the day on your next project.

This is a dynamic wonderful field, go play!

project documentation

This post is about documentation, not source code documentation, but project and process level documentatino. I've spent the last 3 days working on a quick side project at work. There were 10 tasks, none of which were very complicated, the time spent tackling these tasks was about 5 or 6 billable hours. The time spent figuring out how to deploy these changes was about 3 days. The problem, project documentation

Scattered Information
Like some sort of 80's Nintendo Game I had to find the various colored keys to win the game. One developer knew the ftp server's ip address, another the username, maybe a third the password. It didn't help matters that this was a fairly complex site made up of multiple components (third-party blog, storefront, cms) each with their own credentials. Collecting this information was the first hurdle to leap in getting the code and getting the job done. It took a solid afternoon of pinging different parties but I finally had a list of keys, the blue door, the red door, even the green glowing door could all be opened!

Out of Date Information
Then came the crushing realization, as I found that the red door was rusted shut, the green glowing door didn't use a key but a magic potion, and no one could remember exactly where the hell the blue door was even located. The information was out of date or just plain wrong, more time wasted pinging people to get updated information and missing chunks. But after another day of haranguing I finally confirmed that the doors could in fact be opened, that night visions of tables and source code danced in my head.

Misplaced Information
This isn't really anyone's fault. I was working on a type of system, let's call it a foo type system, this particular foo system had been customized for client bar. I looked in the foo\bar\ folder for documentation and came up empty-handed. I assumed that there was no documentation and so created some there to collect up the hard earned bits and pieces of information I was able to pull together. Being proud of my new documentation with things logically laid out, I reported to my fellow developers the great leap forward in documentation technology I had developed. I was told there was similar documentation in the foo\ folder, why no one mentioned this to me earlier when I was pulling together this information is beyond me. But it didn't make sense to my brain, if there is a foo\bar\ folder why isn't foo\bar\ information in it, why is it in foo\, ah!

So what is the solution? Knowledge Base, Sharepoint, Wikis, Word Documents, what to do? I don't think that any one of these things by itself is a solution, but I do have some ideas.

Convention over Configuration
If you've ever played around with Ruby on Rails you will know the great joy of feeling at home in a rails project. Where are my models?! app\models\ that's where they always are, that's where they belong. I think adopting a standard documentation layout structure would be useful. Here's an idea (off the top of my head, so its not very polished)

• project-name\documentation - Root of the documentation
• project-name\documentation\bootstrap - How to get started, pulling the project from source control, initial builds, dev box configuration
• project-name\documentation\credentials - IP Addresses, Username, and Passwords go here
• project-name\documentation\database - Everything you'd want to know about the database
• project-name\documentation\deploy - Deployment specifics are here
• project-name\documentation\vendor\* - Third party documentation goes in various folders here

It's not perfect but its a start, really the important thing would be to have some sort of standard and stick to it.

Wikis
I like wikis, I think they are neat. Your documentation is easily editable, so it's easy to keep it up to date, and multiple parties can collaborate to break the task of documenting a system into more manageable chucks. I also think that you should follow some sort of system when writing them. Make this part of the convention and don't stray from it unless absolutely necessary. Maybe the sections above simply become wiki pages, with subpages. Wiki markup is easy to learn for any programmer, and as long as you aren't doing anything fancy, easy to remember.

Document your processes, that's the big thing, it would be great if you have a convention, its awesome if you have some collaboration medium that let's you keep it up to date, but the most important thing is to document the process. It's been eye opening to write out a list of steps for some of the "simple" tasks I do on a project from time to time. Since its become routine in my head the task is one step, do the task, but when I write it out on paper there are 13 steps with small conditional branches. It seems easy to do a task you've done a hundred times before, but it can be maddening to someone new trying to accomplish that task without the help of the well-worn mental path you've painstakingly claimed from the jaws of chaos.

I have been on projects with great documentation, and some with not so stellar documentation, and it is like night and day. So here's a thought experiment, a trite and cliche one, but if your entire development team got hit by a bus tomorrow and some new guys had to come in and deploy, how long would it take them, could they even do it? The answer should be, they would simply bootstrap then look in deploy and follow my step by step guide to deployment success, if your answer was, they would pray and put on their detective hats, ding ding ding, you've got some documentation work to do.

project documentation

This post is about documentation, not source code documentation, but project and process level documentatino. I've spent the last 3 days working on a quick side project at work. There were 10 tasks, none of which were very complicated, the time spent tackling these tasks was about 5 or 6 billable hours. The time spent figuring out how to deploy these changes was about 3 days. The problem, project documentation

Scattered Information
Like some sort of 80's Nintendo Game I had to find the various colored keys to win the game. One developer knew the ftp server's ip address, another the username, maybe a third the password. It didn't help matters that this was a fairly complex site made up of multiple components (third-party blog, storefront, cms) each with their own credentials. Collecting this information was the first hurdle to leap in getting the code and getting the job done. It took a solid afternoon of pinging different parties but I finally had a list of keys, the blue door, the red door, even the green glowing door could all be opened!

Out of Date Information
Then came the crushing realization, as I found that the red door was rusted shut, the green glowing door didn't use a key but a magic potion, and no one could remember exactly where the hell the blue door was even located. The information was out of date or just plain wrong, more time wasted pinging people to get updated information and missing chunks. But after another day of haranguing I finally confirmed that the doors could in fact be opened, that night visions of tables and source code danced in my head.

Misplaced Information
This isn't really anyone's fault. I was working on a type of system, let's call it a foo type system, this particular foo system had been customized for client bar. I looked in the foo\bar\ folder for documentation and came up empty-handed. I assumed that there was no documentation and so created some there to collect up the hard earned bits and pieces of information I was able to pull together. Being proud of my new documentation with things logically laid out, I reported to my fellow developers the great leap forward in documentation technology I had developed. I was told there was similar documentation in the foo\ folder, why no one mentioned this to me earlier when I was pulling together this information is beyond me. But it didn't make sense to my brain, if there is a foo\bar\ folder why isn't foo\bar\ information in it, why is it in foo\, ah!

So what is the solution? Knowledge Base, Sharepoint, Wikis, Word Documents, what to do? I don't think that any one of these things by itself is a solution, but I do have some ideas.

Convention over Configuration
If you've ever played around with Ruby on Rails you will know the great joy of feeling at home in a rails project. Where are my models?! app\models\ that's where they always are, that's where they belong. I think adopting a standard documentation layout structure would be useful. Here's an idea (off the top of my head, so its not very polished)

• project-name\documentation - Root of the documentation


• project-name\documentation\bootstrap - How to get started, pulling the project from source control, initial builds, dev box configuration


• project-name\documentation\credentials - IP Addresses, Username, and Passwords go here


• project-name\documentation\database - Everything you'd want to know about the database


• project-name\documentation\deploy - Deployment specifics are here


• project-name\documentation\vendor\* - Third party documentation goes in various folders here

It's not perfect but its a start, really the important thing would be to have some sort of standard and stick to it.

Wikis
I like wikis, I think they are neat. Your documentation is easily editable, so it's easy to keep it up to date, and multiple parties can collaborate to break the task of documenting a system into more manageable chucks. I also think that you should follow some sort of system when writing them. Make this part of the convention and don't stray from it unless absolutely necessary. Maybe the sections above simply become wiki pages, with subpages. Wiki markup is easy to learn for any programmer, and as long as you aren't doing anything fancy, easy to remember.

Document your processes, that's the big thing, it would be great if you have a convention, its awesome if you have some collaboration medium that let's you keep it up to date, but the most important thing is to document the process. It's been eye opening to write out a list of steps for some of the "simple" tasks I do on a project from time to time. Since its become routine in my head the task is one step, do the task, but when I write it out on paper there are 13 steps with small conditional branches. It seems easy to do a task you've done a hundred times before, but it can be maddening to someone new trying to accomplish that task without the help of the well-worn mental path you've painstakingly claimed from the jaws of chaos.

I have been on projects with great documentation, and some with not so stellar documentation, and it is like night and day. So here's a thought experiment, a trite and cliche one, but if your entire development team got hit by a bus tomorrow and some new guys had to come in and deploy, how long would it take them, could they even do it? The answer should be, they would simply bootstrap then look in deploy and follow my step by step guide to deployment success, if your answer was, they would pray and put on their detective hats, ding ding ding, you've got some documentation work to do.

camels, underscores, and dashes

I've been learning lisp, oh it is good fun! Go now, stop reading this stupid blog, learn some lisp! Anyone still here, well let's talk about some stuff since you won't obey my commands... yet.

There are stupid things in life that don't seem important but somehow make a big difference. Really stupid things, things you can't image people would ever care about, like Indent style. Not a programmer, don't think it matters, don't think anyone would ever care? Get 10 programmers together, ask them what their favorite Indent style is and watch as the One True Brace Stylistas (the camp I fall into) and the Allmaniacs start screaming obscenities at each other and begin to fashion crude weaponry.

It seems like a small thing, but as programmers we spend a lot of time parsing text with our eyes and our brains. Reading source with a different Indent style can feel like walking with shoes on 3 sizes too big, sure you still know how to walk but it feels clumsy and unnatural.

Lisp can definitely feel like waking up groggy and putting on a pair of rollerblades instead of shoes. Its syntax can be confounding and lots of new comers really hate the parentheses.

(defmacro once-only ((&rest names) &body body)
  (let ((gensyms (loop for n in names collect (gensym))))
    `(let (,@(loop for g in gensyms collect `(,g (gensym))))
      `(let (,,@(loop for g in gensyms for n in names collect ``(,,g ,,n)))
        ,(let (,@(loop for n in names for g in gensyms collect `(,n ,g)))
           ,@body)))))

Note there should not be any semicolons after the ampersands, syntax highlighter keeps putting them in there (if you know how to fix this please feel free to leave a comment)

Now this is a little unfair to lisp, if this is the first code example you've every seen don't be scared off, it uses lots of advanced concepts, and to be honest, I still don't fully grok the double-quoting and double-unquoting that is going on in this thing. The main thing to take away is look at all those parentheses, goodness me! Actually its not really that bad, SLIME does a great job of balancing them and they are semantic not just syntactic. Unlike other languages, in lisp parentheses are signal not noise.

One of the things I love about lisp and find myself wanting to do more and more in other programming languages is using the dash as a separator. The macro that is defined above is named "only-once" and I like that. Typing it is a breeze, there are no shifts to get capital letters or underscores. Depending on the language this would be written as OnlyOnce, onlyOnce, only_once, but lisp lets you type only-once, and although it seems small, I definitely like it more than any other convention.

I'm a web programmer for my 9-5 actually get a paycheck for programming programming, and there are many things that you can name with dashes. Web pages (my-sweet-webpage.html), image resources (guy-dancing-with-cat.jpg), css class (div.super-awesome), html entity id's (my-super-awesome-div) are all legal. I want to be able to use the same convention in JavaScript or C# or PHP or [insert language here] but I can't.

There is good reason why I can't, it would be impossible to program a parser, don't believe me, parse this JavaScript pretending that you can use dashes in names.

var dash-variable = 10
var dash = 8;
var variable = 4;
alert(dash-variable);

What would the output be, 10 because it looked up "dash-variable" or 4 because it looked up "dash"-"variable" = 8 - 4 = 4. The way lisp gets around this is that there are no infix operators. The same code in lisp would look like this.

(defvar dash-variable 10)
(defvar dash 8)
(defvar variable 4)
(format t dash-variable)
; or
(format t (- dash variable))

Slowly but surely though I'm getting used to gliding around on my lisp rollerblades, and when I have to put on my C# shoes or my PHP shoes they just don't feel right anymore. There is nothing I can about this except be aware, and for the love of the flying spaghetti monster FOLLOW THE LANGUAGE'S NAMING CONVENTION.

Because if I come across some of your .Net code and it looks like Java, or you want to write your JavaScript like its a .Net class, you will incur my unending wrath. I might think that capitalizing the first letter of function names is wrong (I'm looking at you .Net, first letter capitalization is for classes) but consistency of source code is much more important than my petty preference. Lunch is over now, back to writing Allman braced CapWords C# code, because at the end of the day, someone pays me to walk around in these crocs, no matter how ugly I think they are.

camels, underscores, and dashes

I've been learning lisp, oh it is good fun! Go now, stop reading this stupid blog, learn some lisp! Anyone still here, well let's talk about some stuff since you won't obey my commands... yet.

There are stupid things in life that don't seem important but somehow make a big difference. Really stupid things, things you can't image people would ever care about, like Indent style. Not a programmer, don't think it matters, don't think anyone would ever care? Get 10 programmers together, ask them what their favorite Indent style is and watch as the One True Brace Stylistas (the camp I fall into) and the Allmaniacs start screaming obscenities at each other and begin to fashion crude weaponry.

It seems like a small thing, but as programmers we spend a lot of time parsing text with our eyes and our brains. Reading source with a different Indent style can feel like walking with shoes on 3 sizes too big, sure you still know how to walk but it feels clumsy and unnatural.

Lisp can definitely feel like waking up groggy and putting on a pair of rollerblades instead of shoes. Its syntax can be confounding and lots of new comers really hate the parentheses.

(defmacro once-only ((&rest names) &body body)
  (let ((gensyms (loop for n in names collect (gensym))))
    `(let (,@(loop for g in gensyms collect `(,g (gensym))))
      `(let (,,@(loop for g in gensyms for n in names collect ``(,,g ,,n)))
        ,(let (,@(loop for n in names for g in gensyms collect `(,n ,g)))
           ,@body)))))

Note there should not be any semicolons after the ampersands, syntax highlighter keeps putting them in there (if you know how to fix this please feel free to leave a comment)

Now this is a little unfair to lisp, if this is the first code example you've every seen don't be scared off, it uses lots of advanced concepts, and to be honest, I still don't fully grok the double-quoting and double-unquoting that is going on in this thing. The main thing to take away is look at all those parentheses, goodness me! Actually its not really that bad, SLIME does a great job of balancing them and they are semantic not just syntactic. Unlike other languages, in lisp parentheses are signal not noise.

One of the things I love about lisp and find myself wanting to do more and more in other programming languages is using the dash as a separator. The macro that is defined above is named "only-once" and I like that. Typing it is a breeze, there are no shifts to get capital letters or underscores. Depending on the language this would be written as OnlyOnce, onlyOnce, only_once, but lisp lets you type only-once, and although it seems small, I definitely like it more than any other convention.

I'm a web programmer for my 9-5 actually get a paycheck for programming programming, and there are many things that you can name with dashes. Web pages (my-sweet-webpage.html), image resources (guy-dancing-with-cat.jpg), css class (div.super-awesome), html entity id's (my-super-awesome-div) are all legal. I want to be able to use the same convention in JavaScript or C# or PHP or [insert language here] but I can't.

There is good reason why I can't, it would be impossible to program a parser, don't believe me, parse this JavaScript pretending that you can use dashes in names.

var dash-variable = 10
var dash = 8;
var variable = 4;
alert(dash-variable);

What would the output be, 10 because it looked up "dash-variable" or 4 because it looked up "dash"-"variable" = 8 - 4 = 4. The way lisp gets around this is that there are no infix operators. The same code in lisp would look like this.

(defvar dash-variable 10)
(defvar dash 8)
(defvar variable 4)
(format t dash-variable)
; or
(format t (- dash variable))

Slowly but surely though I'm getting used to gliding around on my lisp rollerblades, and when I have to put on my C# shoes or my PHP shoes they just don't feel right anymore. There is nothing I can about this except be aware, and for the love of the flying spaghetti monster FOLLOW THE LANGUAGE'S NAMING CONVENTION.

Because if I come across some of your .Net code and it looks like Java, or you want to write your JavaScript like its a .Net class, you will incur my unending wrath. I might think that capitalizing the first letter of function names is wrong (I'm looking at you .Net, first letter capitalization is for classes) but consistency of source code is much more important than my petty preference. Lunch is over now, back to writing Allman braced CapWords C# code, because at the end of the day, someone pays me to walk around in these crocs, no matter how ugly I think they are.