Los Techies

How We Do Things - Specification (Using the right tools)

Scott C Reynolds — Fri, 13 Nov 2009 14:41:52 GMT

This content comes solely from my experience, study, and a lot of trial and error (mostly error). I make no claims stating that which works for me will work for you. As with all things, your mileage may vary, and you will need to apply all knowledge through the filter of your context in order to strain out the good parts for you. Also, feel free to call BS on anything I say. I write this as much for me to learn as for you.

This is part 7 of the How We Do Things series.

This post was co-written with Cat Schwamm, business analyst extraordinaire.

In the last post we talked about how we approach specification philosophically, as an iterative, JIT process. In this post we will take a look at the tools we use to create specifications.

User Stories and Text

User stories and other text documents are the bread and butter of defining work, and we use them like crazy. Our story practice has evolved over time, and we have come to a place where we feel that, when used appropriately, our stories are very effective. For a deeper look at the guidelines we use to construct stories, I recommend you go check out Cat’s post on the subject. Go ahead. I’ll wait.

Okay, welcome back. Here’s the thing, stories and tasks are only part of the equation. Stories alone aren’t enough to define a system, and trying to define everything in text is a fool’s task. (I’ve been that fool). You need a full arsenal of specification tools to do the best job possible.

Story Pros: captures textual data well, tells the story

Story Cons: not everything is meant to be captured in text

Mockups

Mockups are a very useful tool when specifying details of how things should work. With stories, you really can't add a lot of design and implementation details or the signal to noise ratio becomes too high and shit gets overlooked. A basic rule of thumb we employ on the team is "things that don't get communicated well in text shouldn't be forced into a text medium." Basically, if you're going to try to describe the way something should look in a story, a) it's probably not going to look the way you actually picture it b) that story is now noisy as crap and people are going to ignore more important parts. With a mockup, you don't have to take forever to do a flashy, literal, perfect screenshot in Fireworks or anything; you can just drag and drop Balsamiq controls around and voila. Ya got an aesthetically pleasing mockup that humans go nuts over. In five minutes I can mock something up in front of a developer, explain how it works, and they are ready to go.

Another great thing about mockups is that they are extremely useful for getting user feedback on specs without distracting the user that "this is the final product, no more input." You can use a mockup to discuss workflow and layout without getting mired in fine-grained detail. The last time I was at the lab, I went back to my hotel room for a couple of hours and mocked up apps for 4 workspaces, brought them back to the supervisors and was able to get plenty of good feedback and make edits right there in front of them. Gold.

Mockup Pros: Time-saver, gives the gist of what you want, keeps your stories clean while still conveying what you want, good to show to users.

Mockup Cons: Can fall into the trap of putting everything on a mockup just like you would put everything into a story and it's inappropriate

High Fidelity Design

How easy is it to develop from what basically amounts to a screenshot? You know exactly how everything should look, you can strip images out, you don't really have to think about it.

Wait a minute. There's a red flag.

You don't have to think about it? That's a paddlin'. A high fidelity screenshot, while beautiful and easy to work from, gives developers a signal that this screen is a specification set in stone. They see what it needs to look like, they build it like that. It's just like BDUF; the high level of detail and granularity means that people won't think about what they're actually building, they'll just duplicate what they are given.

Screenshot Pros: Hotness, high level of detail, easy to work from

Screenshot Cons: Removes developer thought, can take a long time to create such a design

Conversation and Whiteboarding

While each of these mediums has plenty of merit and many benefits, conversation and whiteboarding are my (Cat's..well, OK mine too) favorite method of specifying work. There is nothing like having the team (or pertinent members) together, talking through the workflow of a feature/app, mapping out how everything works, doodling out a rough idea of what things are going to look like and how things will come together. It is so damned valuable to have the working group together, talking through how things are going to work and getting their input. While business analysts and managers can come together to specify the general nature of how things need to work, having different members of the team around will help to eke out edge cases or problems that may not have been thought of in original discussion.

Conversation is obviously important by itself too; user stories are written to leave plenty of room for conversation. If you lose communication on your team and people just go off to code in the dark, a lot of the intent and original specification is lost.

Whiteboard Pros: Mapping workflow, multiple sources of input, easy to sketch out an idea/easy to change an idea, whiteboarding is fun as shit, conversation fully fleshes out ideas

Whiteboard Cons: Easy to get lost if not captured appropriately

While we’ve clearly chosen a favorite medium, you really can’t use just one. Each medium has a lot to offer depending on the scenario you are working with, and just like any other thing, you have to use what works naturally for the team in context with what you are doing.

Technorati Tags: how we do it, improvement, lean, management, quality, software, team, planning

How to annoy your teammates

bogardj — Fri, 13 Nov 2009 14:22:55 GMT

In 3 easy steps:

Step 1: Perform a change that affects many, many files

My favorite is a namespace rename. Other choices include deleting a core marker interface, renaming a layer supertype class, or changing the folder structure in a project.

Typically, VisualStudio will crash when I do this, though I’m not sure if it’s VS choking or ReSharper. Either way, a large automatic refactoring will cause a crash.

Step 2: After the VS crash, re-open the solution and choose to recover all unsaved files

ReSharper likely made it quite a ways through your refactoring before VS crashed. All those unsaved files were likely cached for recovery by VisualStudio, so you can probably get a lot of those changes back. Instead of choosing to revert your local changes, go ahead and recover all those files. It’s key for maximum annoyance.

Step 3: Merge these recovered files back to trunk

Since this was an enormous refactoring, maybe affecting hundreds of files, you’ll want to merge your changes back to trunk as soon as possible. After all, you don’t want to be the sucker merging after everyone else has finished their work.

When you’re done, your co-workers will be greeted with one annoying merge, and another fun dialog that never seems to quite go away:

Just when you think you caught the last of the recovered files that had its line endings screwed up, another one pops up. They’ll hate you once because of the core change that affected so many files, making it quite annoying to merge back to trunk. But they’ll form that long-lasting, persistent hate because of this dialog box that keeps coming up. Yes, there is that little checkbox at the bottom, but who reads these things anyway?

Willed and forced design

bogardj — Fri, 13 Nov 2009 02:32:19 GMT

Roy Osherove, as a TypeMock employee, presents quite a dilemma from opinionated TDD blog posts simply because whether he has one or not, there’s always the question of agenda. Which is quite unfortunate, everyone has some sort of selfish agenda at some level. One of those posts came up in a commentary on willed and forced design, with respect to the usage of mocking frameworks:

#1 Willed Design

By writing tests, you can observe the usability of your design from a consumer perspective, and can decide whether or not you like it, and change it accordingly

#2 Forced Design

By using a subset of the available isolation frameworks(rhino, moq, nmock) or specific techniques *manual mocks and stubs) you discover cases that are not technically “mockable” or “fakeable” and use that as a sign for design change.

After about 2 seconds of playing around with dynamic languages such as Ruby and JavaScript, the idea that TypeMock is some how “impure” seemed rather silly. Yes, it bends the CLR in crazy ways, but in and of itself, I believe it has its place.

However, I highly disagree with Roy that #2 is bad, that a tool shouldn’t force my hand in a design. But there’s a bit of a straw man here – it’s not the tool forcing my design, it’s the test telling me where I need to change my design. Quite simply, if I run up against something hard to test, my first choice is to isolate that piece. Here’s an example:

public ActionResult Index()
{
    var user = Session["CurrentUser"];

    return View(user);
}

This piece is awkward to test, even though HttpSessionBase or whatever is a class with virtual methods, and it makes the test ugly. Yes, I could mock the crap out of this heavyweight object, but that’s not really helping me out, is it? Instead, I’ll isolate the ugly:

private readonly IUserSession _userSession;

public HomeController(IUserSession userSession)
{
    _userSession = userSession;
}

public ActionResult Index()
{
    var user = _userSession.GetUser();

    return View(user);
}

Instead of using a dictionary directly, I’ll hide that business behind a facade service, keeping the dictionary ugliness and duplication in one highly cohesive class. But it was the _test_ that led me to do this, because I’m tuned in to pieces that are hard to mock. File I/O? Facade. Web service proxies? Facade. Registry, HttpContext, etc. etc? All facade. I want to isolate my core application from the untestable pieces, not because they’re necessary untestable, but because I don’t want to couple my application directly to these external services. Putting these behind targeted facades eliminates all that duplication that directly using these APIs tends to encourage.

There are plenty of APIs that slapping a simple facade over tends to make things worse, not better, such as:

Workflow Foundation
SharePoint

And any other framework that requires you to tiiiiightly integrate with in order to be successful. So where does that leave me and TypeMock? Well, I don’t use any of those frameworks that require tight coupling, and I don’t have any pain with my current tool of choice in .NET (Rhino Mocks), so why switch exactly? For those rare occasions I might need TypeMock (DateTime.Now), I already have a solution I quite like. Yes, TypeMock could be free, but the only compelling reason I’d switch would be to another free tool with a better, clearer to write, read and scan API.

How We Do Things - Evolving our Specification Practice

Scott C Reynolds — Thu, 12 Nov 2009 21:59:14 GMT

This is part 6 of the How We Do Things series.

This post was co-written on Google Wave with my colleague Cat Schwamm, who keeps me sane every day.

In this part we will explore how specification practice has evolved in our team, from a very waterfallish BDUF approach to what currently is a very lean approach to specification. In the next part of the series we will talk stories and mockups and other tools we employ to make the magic happen.

Where we came from

We began our large LIS project in late 2004, starting with about 6 full months of writing specifications and designing the database. We created reams of documentation for each application complete with use cases that we knew we wouldn't even implement until after the first version was released (sidebar: some of those still haven't been done). We defined more than 100 tables of heavily normalized database schema. Before one line of code was written, we had spent six months of project budget.

As development continued on the project we found ourselves diverging from the specifications that had been created. The documents became little more than a roadmap, with the bold headers on functional groups and the basic usage stories becoming the guidelines that we followed. Much of the detailed specification and database schema went out the window as the system took shape and people began to see and give feedback on what was being produced. Too much specification gave us a false sense of "doing it right" and led us down many wrong paths. Balancingrework with completing planned features became a costly chore.

By the time the project was complete, it was clear that much of that up-front work had been wasted time and money. Had we top-lined the major milestones of such a large project, detailed a small set of functionality, and started developing iteratively, the system would have taken form much sooner, allowing for a tighter feedback loop and much less overall waste.

How we do it now - Overview

Lessons learned, we set about improving how we do specification. I already talked a little about this in the posts on planning, so please review those if you haven't seen them yet. [part 1] [part 2]

When planning a new project of any size, we take an iterative approach. We start at a very high level, and strive to understand the goals of the project. What need does it serve? Who will be using it? Are we competing with something else for market share? Is there a strategic timeline? What's the corporate vision here? What are the bullet points? We will fill in details later. We only want broad targets to guide us further.

When we get closer to development, we start to identify smaller chunks of functionality within each of those broad areas. This is still pretty high level, but done by business analysts and management on the IT team. We start to identify MMFs (minimal marketable features) and group them up in order of importance to help determine next steps.

MMFs in hand, we take the first one and start defining it further. This is where the information from the planning post comes in. We start to write stories (Cat has a great post detailing how to build effective stories). The other information gathered to this point sits dormant, with as little specification work done as possible, until such time as we are getting closer to working on it.

Over time, and only as needed, we put more and more specification on the system, and this is done in parallel with development. In fact, often the most specific information can only surface during development of those features, as they take shape, and as we understand how users will react. Specification should be every bit as iterative as coding.

Reduced to its essence, we JIT specification at many levels to allow maximum flexibility to change direction with minimal wasted work.

Gemba is an essential part of specification

It's often the case that a team relies on "domain experts" to provide them with the specifications they need to build software. This is the BDUF way - gather in committee and have the all-knowing user tell you what to build. Fail.

Cat sez:

The dev team works out of the corporate office in Florida, while the actual laboratory is located in upstate New York. As a result, it is often an exercise of the imagination to figure out the best way to create things for them. Before I visited the lab, I relied on information from others, emails back and forth to the lab crews working all weird hours of the night, and my knowledge of the applications currently in existence. I really only ever got half the picture, and it was difficult to ensure that the things I was specifying would fit into the lab users workflow well without actually knowing what was going on up there. When I visited the lab my whole world was changed. Actually seeing how users interacted with the software and seeing ways they would work around what we didn't have (open Excel or Word documents on their desktop, a wall covered in post-it notes). Just from walking around talking to people for 2 days, I probably got 50 requests. And they never would have asked for them; they would have just kept suffering. Being there showed me everything about how they worked and a million ways I could improve their lives. The experience was invaluable to both me and them, and each subsequent trip has just improved my knowledge of the way we work and the way they interact with our software.

There is no substitute for a certain amount of domain expertise being resident in the team room. Your domain experts are experts only in their domain. They may know the workings of a histology laboratory inside and out, but if you ask them to design a system to support that lab, they'll come back with something that looks an awful lot like excel and post-it notes.

Yes...this is a workaround someone had for something our system didn't do. It's been fixed ;)

Lean has a concept of the gemba attitude and genchi genbutsu, essentially, being in the place where the action happens. Developers and business analysts have to work with the domain experts, in the place where the work happens, and observe the true workflows in place before hoping to design a system to support them. You cannot get this information from sit down meetings and emails with domain experts. You must go and see for yourself, or you will miss things.

In the next post we will talk specifically about the tools and techniques we use to specify work, and how we combine them to form complete pictures of a system (spoiler alert: it ain't just stories).

Technorati Tags: how we do it, improvement, lean, management, quality, software, team, planning

Going Away Geek Beers

Scott C Reynolds — Thu, 12 Nov 2009 14:47:43 GMT

Most of you have heard by now that I am leaving Florida for the concrete pastures of New York City.

I'd like to have a get-together of some of the Florida community guys (and gals) Monday, Nov 16, in Ocala at 7pm until we decide to leave.

It's truly been a pleasure working with this community over the last few years, and I will miss you guys. So..come on out and buy me a beer! ;)

Location: O'Malley's Alley

My phone is 352.209.0943 drop me a line if you get lost of want to confirm you're coming. So far looks like a real good group will be there, including Cory Foy, Sean Chambers, Scott Densmore, and Will Green, the amazing Cat Schwamm as well as members of my team. Hope to see you Monday!

Electronic Kanban Tools and WIP Limits: LeanKitKanban and AgileZen Get It!

derick.bailey — Mon, 09 Nov 2009 17:55:24 GMT

Most of the electronic Kanban boards that exist simply don’t understand what WIP limits are really about. They all seem to go down the path of forcing any step (column) in the process to have a maximum limit that is very hard and fast. They set it up so that you cannot add any more items to the step than the limit allows. But the truth about WIP limits is that they are not supposed to be hard and fast, mechanical limits. Putting in a hard limit like this is a great way to destroy the productivity of a team and usefulness of a tool when the team finds themselves in a crunch, in a situation with additional resources and needs, or any of a number of other circumstances.

I know I haven’t been vocal about this online, but it’s something I’ve been complaining about to my coworkers and friends for a while. It bugs me and is one of the major reasons that I’ve stayed away from the major (free) players in the electronic Kanban realm, other than trials and basic testing of the systems.

But then I got an email from Chris Hefley this morning, about some new features in LeanKitKanban. When I logged in to check them out, I was surprised to see this happen when I tried to exceed a column limit:

I can’t tell you how happy I was to see this! Finally, one of the tools vendors in this space is really starting to get it! For this, and a few other reasons that I don’t want to talk about yet, LeanKitKanban is now officially my favorite electronic Kanban / task board around. If you haven’t done so, I highly recommend that you check them out.

Do any other electronic Kanban boards are heading down this same path and allowing for limit overrides? If your current tool doesn’t support this, it should.

Update: Looks like AgileZen is getting this feature in the next release (see Nate’s comments below). that’s great news! I’ve been impressed by this tool as well. the support for soft WIP limits in multiple tools is starting to show some real competition and innovation in the market space. that’s good news for everyone!

Fields and virtual members

bogardj — Mon, 09 Nov 2009 14:40:25 GMT

It seems like the sillier the bug, the more time you’ll spend debugging it, simply because it’s in functionality you just knew that worked correctly (and had the tests to back it up). One problem we hit recently was code that used fields to back virtual properties:

public abstract class Enumeration : IComparable
{
    private readonly int _value;

    protected Enumeration() { }

    protected Enumeration(int value)
    {
        _value = value;
    }

    public virtual int Value
    {
        get { return _value; }
    }

    public virtual int CompareTo(object other)
    {
        return _value.CompareTo(((Enumeration)other).Value);
    }
}

This isn’t a problem in and of itself, except in the behavior of that last method. Notice its logic uses the field and not the property. I can then define a derived type:

public class PercentDiscount : Enumeration
{
    public override int Value
    {
        get { return 5; }
    }
}

But now my CompareTo method breaks because it isn’t using the correct value. It uses the uninitialized field, causing all sorts of bizarre behavior. When you have logic errors in places like GetHashCode, Equals or CompareTo, I can guarantee your application will break in the most hair-pulling ways imaginable.

Let’s fix it

So what’s a better option? We could just “make sure” that we don’t use the private field, and only use the virtual property. But I hate conventions that rely on my memory to not make a mistake, I want to fall into the pit of success. One way to do so is to use automatic properties:

public abstract class Enumeration : IComparable
{
    protected Enumeration() { }

    protected Enumeration(int value)
    {
        Value = value;
    }

    public virtual int Value
    { 
        get;
        private set;
    }

    public virtual int CompareTo(object other)
    {
        return Value.CompareTo(((Enumeration)other).Value);
    }
}

Instead of a backing field, we’ll use an automatic property, making it impossible to use a non-virtual backing field. We still get the same access modifiers (a virtual, overridable getter, a private setter), plus the benefits of automatic properties. So now I’m curious: are there any valid reasons to keep using fields for holding state?

Happy Hack-o-ween: Electronics and a microcontroller spice up the haunt

Sharon J. Cichelli — Sun, 08 Nov 2009 16:27:00 GMT

Ah, Halloween, when a young woman's fancy turns to love. And zombies.

I had two personal requirements for the costume I would build this year:

It shall be spooky.
It shall blink.

I'll tell you about the final result, the electronics and the software that went into it, plus the techniques I used to achieve wearable electronics. I'll introduce you to the Arduino, an open-source microcontroller prototyping platform, which is an exhilarating tool/toy for making your software skills manifest in the physical world.

My husband and I have been teaching ourselves electronics. A few months ago, Dad taught me to solder. I recently read Syuzi Pakhchyan's excellent primer on wearable electronics and smart materials, Fashioning Technology. And I've been making things with my Arduino. All these ideas were swirling and combining in my head to inspire this year's Halloween project. Er, costume. Same difference.

What was I? I was a nightmare... the thing under your bed... the reason for your well developed sense of paranoia...

I sported a crop of writhing eyeballs erupting from my head. Each eyeball has an LED inside it, and they blink randomly and independently, until I trigger a hidden switch, which causes the blinky ones to go dark and two red eyes to pulse menacingly. In the Flickr photoset, you can see the construction process.

The Arduino Sketch

The term "Arduino" is overloaded to mean:

a particular chip and circuit board which you can buy or build;
the IDE in which you write programs for the chip;
the language, which is C-flavored;
fun.

Arduino programs are called sketches. Every sketch must contain two functions: setup (runs once) and loop (runs continuously). Here's my sketch, with extra explanatory comments, that blinks the six regular eyeballs and responds to the switch by pulsing the red eyeballs.

    1 #define SWITCH 8

    2 int ledPins[] = {2, 3, 4, 5, 6, 7};

    3 const int ledPinsCount = 6;

    4 int redEyePins[] = {10, 11};

    5 const int redEyePinsCount = 2;

    6 long durations[ledPinsCount];

    7 int ledStates[ledPinsCount];

    8 long previousTimes[ledPinsCount];

    9 int i;

   11 void setup()

   12 {

   13   pinMode(SWITCH, INPUT); //Specify the switch pin as an input.

   15   for (i = 0; i < redEyePinsCount; i++)

   16   {

   17     pinMode(redEyePins, OUTPUT); //Specify each red-eye LED pin as an output.

   18   }

   20   for(i = 0; i < ledPinsCount; i++)

   21   {

   22     pinMode(ledPins, OUTPUT); //Specify each regular LED pin as an output.

   23     ledStates = random(1); //Randomly set the LEDs to on or off (1 or 0).

   24     durations = GetRandomDuration(); //Define a random duration for each LED to stay in that state.

   25     previousTimes = 0; //At time of setup, the "last time we changed" is at 0 milliseconds, the start of time.

   26   }

   27 }

   29 void loop()

   30 {

   31   if (digitalRead(SWITCH) == HIGH)

   32   {

   33     TurnOffLeds();

   34     PulseRedEyes();

   35   }

   36   else

   37   {

   38     for(i = 0; i < redEyePinsCount; i++)

   39     {

   40       digitalWrite(redEyePins, LOW); //Turn the red eyes all the way off.

   41     }

   43     for(i = 0; i < ledPinsCount; i++) //For each LED:

   44     {

   45       if (millis() - previousTimes > durations)

   46       {

   47         ChangeLed(i); //If this one's duration is up, then flip it.

   48       }

   49     }

   50   }

   51 }

   53 void TurnOffLeds()

   54 {

   55   for(i = 0; i < ledPinsCount; i++)

   56   {

   57     digitalWrite(ledPins, LOW);

   58   }

   59 }

   61 void PulseRedEyes()

   62 {

   63   //Fade on, then off.

   64   int j;

   65   for(j = 0; j < 255; j+=5)

   66   {

   67     for(i = 0; i < redEyePinsCount; i++)

   68     {

   69       analogWrite(redEyePins, j);

   70       delay(10);

   71     }

   72   }

   73   for(j = 255; j > 0; j-=5)

   74   {

   75     for(i = 0; i < redEyePinsCount; i++)

   76     {

   77       analogWrite(redEyePins, j);

   78       delay(10);

   79     }

   80   }

   81 }

   83 void ChangeLed(int ledPin)

   84 {

   85   previousTimes[ledPin] = millis(); //Update the "last time we changed" to now.

   86   durations[ledPin] = GetRandomDuration(); //Give it a new random duration.

   87   ledStates[ledPin] = 1 - ledStates[ledPin]; //Flip the state between on and off.

   88   digitalWrite(ledPins[ledPin], ledStates[ledPin]); //Set the LED to that state.

   89 }

   91 long GetRandomDuration()

   92 {

   93   //Random number between 1 and 10, then multiplied by 400 to give it a detectable duration.

   94   return random(1, 10) * 400;

   95 }

I like the way the eyes blink independently. If they all flashed in unison, they would look like Christmas lights, and you would notice that two were "special" because they weren't flashing. Instead, the duration that any given eyeball is lit or dark constantly changes.

The blinking is managed by a collection of arrays. One array represents each of my LED pins, so that I can address them in a for loop. The three other arrays hold: the state (on/off) of each LED; the duration each LED should stay in that state; the reading from the millisecond counter when the LED last flipped its state. Each time the loop function executes, if the switch is not connected, then I look at each LED; if the difference between the current time and the time when it previously changed is greater than its duration, flip its state (from off to on, or from on to off), randomly assign it a new duration, and record "now" as the new "previously changed" time. If the switch is connected, then I make the red eyes fade on and fade off.

Fading with PWM

PWM (Pulse-Width Modulation) is a technique for making a digital component (one that turns on or off) simulate analog behavior (be a little bit on, and then a little bit more on). If you turn an LED off and on really quickly, you won't perceive the flickering, but it will look half as bright, because it is actually off for half the time. If you let it spend a little more time off than on, it will appear even dimmer. So by varying the width of the pulses, you can control how bright the LED looks.

The Arduino comes with built-in PWM functions; some pins are already set up to be PWM pins. If you plug an LED into one of the PWM pins, then you can write to it as if it were an analog component. That's why, in my sketch above, I set the brightness of the red eyes using analogWrite(), instead of digitalWrite(). My for loop increments the counter j from 0 to 255, and sets the brightness of both red eyes to the value of j. The Arduino takes care of (imperceptibly) flickering the LEDs with the right ratio of on-time and off-time to achieve a j amount of brightness. So the eyes get gradually brighter, then gradually dimmer. (Then control returns to the main loop function, but if my switch is still connected, the red eyes will throb again.)

Snaps: Wearable Plugs

A metal sewable snap is like a plug for your clothing, an interface between the world of textiles and the world of wires. This is handy when you need the electronics to be separate while you are getting into the clothing, or if you want to wash the clothing. My Arduino hung out at the base of my neck, to be near the LEDs on my head but hidden underneath my wig, but my control switch was near my hip. I could have run a wire down to the switch, but conductive thread was more subtle and more comfortable.

To complete the connection, I soldered a short wire to one side of the snap. That wire plugged into a pin on the Arduino. The conductive thread ran from the switch at my hip up to the back of my dress near the Arduino, and I sewed that conductive thread to the other half of the snap. When the two halves are snapped together, the wire and the thread make a complete connection, as if they were one continuous wire.

I had two threads (going out to the switch and back), so I encased them each in a bias tape tube, to prevent them from touching each other and shorting out.

I've been saying "switch," but actually, I simplified at the 11th hour. I tied each thread around a safety pin, and stuck the pins to my dress. When the safety pins touched each other, they completed the circuit, which the Arduino sketch interpreted as triggering the switch—cue red-eye glare.

What's Next

Soldering and sewing are both liberating skills to possess—they free up your creativity to make wilder and more integrated stuff. If you are currently proficient with only one, ask around and see if you can find a buddy who's good at the other, and teach each other.

The Arduino comes with a great community of hackers and makers, lots of people to learn from and collaborate with. Definitely check it out. There is lots of fun to be had, and blinking LEDs is the barest beginning of what it can do.

Using MSDeploy to automate your Enterprise Application remote deployments.

erichexter — Fri, 06 Nov 2009 17:00:00 GMT

MsDeploy is a newish technology that is a bit schizophrenic. What I mean is that it is a tool that is useful to both Developers and Administrators but it is not clear from the documentation how to best use the technology and how to approach it. I believe it stated as a Server Administrator tool and the team was able to work in an integration with Visual Studio which made it into a more robust framework, but at the same time left is command line interface with so many options that it is challenging to get a grasp on. To top that off the Web Platform Installer uses the MsDeploy packages as a way to distribute packages through that tool. After working through some various ways to use the technology I have settled into some commands that work well for our projects.

Let me set the context of how we are using the tool and what we already had in place so that you can better understand if my use of MsDeploy will work for you. At Headspring we use Continuous Integration on all of our projects and as a result, once our software is built by our build server the next logical step is to deploy our software to a server and than run User Interface tests against the application. Most of our projects are web applications running on ASP.Net MVC using Sql Server as the back end. We install our software using a lightweight zipfile that contains the web application files, database migration scripts and a deployment script which can poke config files and execute our database migration tool. We already have all the pieces in place to deploy our application on a local machine.

Up until know we have used two methods to deploy instances to remote machines. The first methods was to install Cruise Control.Net on the server and have it monitor our source control repository for a new installation package being committed to the repository. Once it sees a new package CCNet will pull down the package, install it locally and go on its merry way. The second method, is to kick off the deployment from the build server and connect over the network to the target database to run upgrades and then xcopy the files to a unc share. Both of these methods require setting up some configuration on our target servers. My goal with our deployments is to reduce the amount of per server configuration we do on each server and use some conventions to make each server look similar to one from a different project.

Using MSDeploy allows us to do the following.

1. Remove the need to install cruise control on the target server and update the configuration for cruise control on each target server. We do have to install MSDeploy on each server but we do not have to mess with any configuration after that.

2. We do not have to mess with setting up unc shares and deal with the mess. It sounds like a silly thing but by getting away from the unc share we can also test our deployments from any machine and msdeploy is actually firewall friendly. xcopy to a unc share is not firewall friendly which means that we cannot use it for all of our clients which means variations between our projects.

3. We use msdeploy as a mechanism to distribute our deployment packages and then remotely execute the packages. This means I can have a single instance of our Continuous Integration server which reduces the number of places to maintain configuration. That is a big win. This also means the log files for all of the deployments can be tracked in a single place.

4. Another benefit of using msdeploy to push our deployments means that I can easily setup new instances of a test configuration and push it to multiple servers without having to log into each machine.. This is good for efficiency.

Our use of MSDeploy now boils down to two steps. Distribute and Execute. We have some of our scripts in NAnt and we are in the process of migrating to PowerShell now that version 2.0 is available from the older operating systems. Below is a sample of executing msdeploy from a NAnt script.

Calling MsDeploy from Nant

The dirPath command tells MSDeploy to synchronize a directory from the source computer a target computer. This is a pretty easy command to understand.

The second command is the runCommand this command was added between the RC and 1.0 release of MSDeploy and I am so happy they added it. The run command is told to execute a command on the remote machine. Since we are running installation scripts, they do not execute instantly and as a result the waitInterval and waitAttempts need to be specified so that the command does not timeout before it has completed running. other than that the output of the console application is piped back to the source computer. The one caveat about the run command is that when it starts it runs from the C:\windows\system32 directory. In order to work around this issue I have found that passing the directory of the command into the batch file that I run allows my batch files to first cd to that directory as its first step. This is a pretty harmless thing to do and works pretty well.

This is what a sample deployment batch files looks like.

cd %1
rd ..\codeToDeploy\ /s /q
applicationNamePackage.exe -o..\CodeToDeploy\ -y
cd ..\CodeToDeploy\
cmd /c %systemroot%\system32\inetsrv\appcmd stop site applicationName_dev
iisreset
call dev.bat
cmd /c %systemroot%\system32\inetsrv\appcmd start site applicationName_dev

This is pretty basic and does some IIS commands as well.

I am sure I left some information out, but I wanted to get a brain dump of our use of MSDeploy.

Long term I would like to see the use of PowerShell driving msdeploy and adding some configuration around each Server Role in an application and tie it to the servers needed for each environment. I have started a project to put this together called psTrami but I have not put any of the code together yet, just some small spikes to prove it out.

More to come sometime soon…..

Hang in there baby birds, I'll feed you

Scott C Reynolds — Thu, 05 Nov 2009 20:19:29 GMT

Quick housekeeping note - How We Do Things series is not cancelled, I haven't given up on it or run out of steam, it will still press forward.

Trying to get a lot wrapped up both at home and at work in preparation for my move to New York, so I lapsed a bit, but I will be back on it soon.

Automapper Auto Profile Registration.

erichexter — Thu, 05 Nov 2009 03:24:15 GMT

On some of our projects we have been experimenting with smaller AutoMapper profiles. The idea is that it is easier to digest a smaller profile. We have gone so far as creating a profile for each Domain object and handle all of the mappings to and from the domain object. We are also trying out a Profile per scenario. While these smaller profiles are easier to dig in and understand, the registration of them are a little painful. So I put together a quick way to auto register all the profiles for automapper. Below is the code to discover all the profiles in an assembly than register them with AutoMapper. There is nothing fancy here and I could certainly spend more time making it better performing, but realistically this is startup code that runs once at application start up. That being said I would rather focus performance optimization efforts on places that actually make a difference to the End User Experience.

Here is the sample.

It is important to know that we have full code coverage over our application including integration tests, so that if something were to break as a result of loading this in a non deterministic order, we would know before we commit our changes to source control.

Here is the code for the ForEach extension method, since I breezed over it.

This is a smaller post than I normally put together.. is this small of a post useful?

A Time For Change

derick.bailey — Wed, 04 Nov 2009 15:36:03 GMT

Change comes in groups of three, right? Well, I have a 4 week old baby girl (I can hardly believe she’s 4 weeks old already). That would be change #1. For change #2, I turned in my two week notice to my current employer on Monday.

Starting on November 16th, I’ll be joining up with fellow LosTechie, Joey Beninghove, over at TrackAbout.com. I’m excited about the opportunity. There’s a great bunch of developers on that team and it should be a lot of fun and a significant challenge for me, at the same time.

Now I just have to wait and see what change #3 is going to be…

ASP.Net MVC Portable Area – Part 4 IoC framework support.

erichexter — Wed, 04 Nov 2009 05:00:00 GMT

Part 1 – Introduction
Part 2 – Sample Portable Area
Part 3 – Using of a Portable Area
Part 4 – Using an Inversion of Control Framework. (this post)

Using an Inversion of Control Container is a common scenario that would be needed by a Message Handler. The Bus has an extensibility point to create the handlers. The model for this should feel similar to the ControllerFactory extension point in the ASP.Net MVC framework. The sample below shows how to create a Message Handler factory for the StructureMap framework.

The SetMessageHandlerFactory method should be called once at application startup. Other than that … this is a pretty simple way to add a Dependency Injection Framework support to the Portable Area infrastructure.

This makes it pretty simple for your message handlers to use constructor injection to manage their dependencies.

ASP.Net MVC Portable Areas – Part 3

erichexter — Tue, 03 Nov 2009 17:00:00 GMT

Using a Portable Area

This is the third part in a series about using a Portable Area (PA) using MvcContrib. This sample walks through the Host Application side of consuming the Login Portable area. This example demonstrates how a portable area such as a login can send messages and recieve responses from the host application. This allows the host application to control the core of the application and lets the Portable Area solve the User Interface portion of the Login. While this is a pretty simple example it is important to look at the concept of what a Portable Area could solve. A portable Area could just handling wiring up multiple user interface screens and deal with simple form validation while leaving a lot of from for the host application to control the parts that are important to the application. Or a Portable Area could provide an entire self contained piece of functionality like a Blog engine, or mulit-instance forum. There is a large spectrum for how much the Portable Area could provide. This example focuses on an example where the Portable Area provides the UI and lets the host application own the domain logic.

Part 1 – Introduction
Part 2 – Sample Portable Area
Part 3 – Using of a Portable Area (this post)
Part 4 – Using an Inversion of Control Framework.

In order to use a Portable Area (PA), the following references need to be added to your MVC project: MvcContrib & the assembly of the Portable Area.

Wiring up the Portable Area to the application is done at startup. Portable Areas use the message bus as a way to communicate between the PA and the application. The main method for integrating with a portable area is to register a Message Handler. The sample below demonstrates wiring up a LogAllMessagesObserver, LoginHandler, and a ForgotPassword Handler for the Login Portable Area.

The call to the InputBuilder.Bootstrap() is required to initialize the Embedded Resource view engine used by this Portable Area infrastructure.

Here is an example of an Observer message handler. This handler simply logs the message to the debugger. This could be used to collect metrics about the system, or log messages to a loggin framework. The idea of an observer is that it is looking at the base message and not modifying the state of the message.

The Login Message Handler receives the login request and than sets the result object which is part of the contract that is specified by the LoginPortableArea from Part 2.

In this example the main logic for login is still in a authentication service. The handler is just used to wire up the message and response of the portable area to the host applications domain services.

Whats Next?

The constructor of the LoginHandler takes an IAuthenticationService as a dependency and my next post will walk through how an Inversion of Control container can be connected to the Bus to allow the framework of your choice to put your pieces together.

ASP.Net MVC Portable Areas – Part 2

erichexter — Mon, 02 Nov 2009 17:00:00 GMT

Sample Portable Area

This is the second part in a series about creating a Portable Area (PA) using MvcContrib

Part 1 – Introduction
Part 2 – Sample Portable Area (this post)
Part 3 – Usage of a Portable Area
Part 4 - IoC Framework Support

To create a Portable Area, the first step is to create a separate class library project for the Portable Area. The output assembly is the single file needed to add this functionality to applications which wish to consumer it.

The minimal references required for the Portable Area are shown below:

While DataAnnotations is not required to build a PA, using DataAnnotations for Model validation makes distribution of the PA very easy, since the MVC2 DefaultModelBinder supports the DataAnnotations validation out of the box. If you choose a different validation framework than you would need to distribute those assemblies or possible IL Merge them into your PA.

The sample PA in the MvcContrib project is a Login Portable Area, this is a pretty simple example, but demonstrates how a PA and application can integrate. This is also a piece of functionality that most applications need.

Below is the code listing and structure for the project. It looks identical to a mulit-project ASP.Net MVC Area.

The first difference between creating a Portable Area and a standard area from the files perspective is how the Views are registered with the project. The views Build Action should be changed from content to an Embedded Resource. This allows the views to be embedded into the output assembly so that they view folders and files to not have to be manually copied into each application that uses it. Instead a special view engine will pull these views out of the assembly at run time and render them the same way that a physical view would be rendered.

The second item that is needed to create a Portable Area is a specialized registration class for the that inherits from PortableAreaRegistration. This class provides an extended RegisterArea method that sends in the MVC AreaRegistrationContext and a IApplicationBus object to the method. The IApplicationBus is the mechanism that a Portable Area uses to send messages to the hosting application during. The use of the bus during registration is not required, but it is available in case and specific start up logic is needed to correctly configure the Portable Area.

The last line of the method show how the Portable Area registers the embedded views with the view engine, using the call to the RegisterTheViewsInTheEmmeddedViewEngine method.

An important caveat around the setup of the Registration class is to make sure that the Registration class is sitting in the same Namespace as the controllers and views. If the Namespaces do not match the views will not be able to be located. Since the namespace for the Embedded Resource views cannot be specified declaratively they are created using the Assemblies Default Namespace and the folder structure that they are stored in. So keeping all of these properties consistent will make everything work. If you change the default namespace of the project, you will need to update the namespace of your registration and controller classes.

The first call in this registration method sends a message to the hosting application. This is a contrived example but it demonstrates sending a tracing message that can be used by an observer message handler to log the registration activity. This tracing can be useful since the Portable Areas use the built in MVC registration mechanism for auto discovery and there is not a lot of visibility into the built in registration process. This example shows how a message can be sent between the PA and the hosting application.

The LoginController demonstrates the functionality needed to handle displaying the login form and then handling the form post. There are two Actions in the controller, one to render a Login View and a second Action to process the form post and redirect the user on success or , in the case of a login failure, display the login error messages to the user.

The message bus is the main mechanism for communicating between a portable area and the hosting application. This is a very simplistic mechanism that allows the Portable Areas to communicate with the hosting application in a synchronous manner.

For some scenarios, like when the area should not implement its own database, the host application can own how the domain model is persisted in data storage and the Portable Area can worry about handling the multi-page user interface and other user interface concerns like validating simple data types.

The messages that are passed to the Bus are shown below.

The LoginInput represents the data that is collected from the Login screen. It is using the built in DataAnnotations attributes to handle the simple validation rules.

The result object is used to determine if the credentials were valid for the host application and are then used to either display the error message or redirect to a protected page. Since the LoginInputMessage is passed to the bus with a reference, the handlers in the host application can change the Result object's state and the portable area can than access the Result and determine the correct logic to perform given that result. The implementation for the handlers will be in the next post in this series.

The Index view for the login uses the MvcContrib Input Builders to render a standard form to the page. The use of the Input Builder allows an host application to override any of the html mark up using the Input Builder partials. This means that the Portable Area and Input Builders play very nicely with each other.

This is what the view looks like in a browser.

This is the validation errors that are handled by the Portable Area, using the MVC 2 default model binder.

This shows an error message that is passed back from the resulting application. Other rules could be applied as well.

This is the approach for creating a Portable Area (PA) using the MvcContrib Portable Area feature. Let me know what you think about this approach, we tried to stay with the simplest approach that could possible work, and focused on making it easy to both develop and consume the Portable Areas.

Please leave your comments on what you think of the approach.