Drew Colthorp and I worked with Peter Beaugard, Kari, and Ben on turnDetroit for the weekend. In a nutshell, turnDetroit’s goal is to promote community involvement in identifying, funding, and pursuing opportunities to make productive use of vacant spaces. We were reminded of a few important lessons throughout the event, and our project in particular illustrated that the most important problems to solve are often not technical in nature.

The most important problems are frequently non-technical

Non-technical problems can be very interesting, challenging, and rewarding to take on. Still, as developers, it can be easy to jump into building software when a short deadline looms on the horizon. We spent a lot of time as a team working out exactly what problem we were trying to solve, how to engage communities, how to process incoming ideas, and how turnDetroit could make enough money to be self-sustaining. Peter had alreay put a lot of thinking into the concept of turnDetroit and that helped frame our minimum viable product discussions.

Software was involved in our proposed solutions to the problems identified, but the type of software needed is not particularly challenging or unique. The approach to personal interactions was much more valuable to define.

Prioritize, prioritize, prioritize

It was critical to focus on the product we really needed from our limited time: the pitch. We prioritized tasks that would help build a good story for the pitch. Ben worked diligently on a video to illustrate the concept, Kari and Peter focused a lot of energy on the pitch slide deck, and Drew and I focused in on wireframes for the idea intake, discovery, and funding tasks. Keeping post-it notes hung on the wall identifying our high-value personas and stories helped keep us focused.

Still, we found ourselves off in the woods for an hour or two. Of course Drew and I wanted to build some sort of software to show off during the pitch (we are software developers) and we gave it a brief try. But it came to an end as we were reminded of another lesson:

Frustration saps energy and motivation; success rejuvinates

The technology side of our mockup came together relatively quickly thanks to a combination of familiar and new tools (Staticmatic2, Twitter’s Bootstrap). We had a reasonably functional and flexible layout for the content we wanted to show, but it needed more design attention. Drew and I stated integrating aspects of the design aesthetic from a pre-existing slide deck but were struggling with adapting it to the needs of the web content.

Combined with the already long day (9am to 7pm at that point), the frustration of striving for successful visual design without success left us both nearly ready to call it a day by 8pm. We felt exhausted and unmotivated.

Amazingly, after we aborted that attempt, took a brief break, and then focused on putting together a few Balsamiq mockups (something we’re quite good at) we regained our motivation and worked steadily until 11pm.

We’ve seen this pattern before. It’s a big reason why we find it worthwhile to spend time crafting tools. The less we feel like we’re banging our heads against technology, the more energy we have to solve the problems our customers are more interested in. Good tools more than pay for themselves in the long run.

There’s a lot of positive energy in Detroit

We got to meet awesome people, work on a few great projects, and see first-hand the entrepreneurial spirit at work in Detroit. I hope we’ll see a few of the winners at the Michigan Lean Startup Conference in Grand Rapids on May 17, and I expect We’ll be back to spend some time in Detroit again soon. Well done, everyone.

You can download the template here.

We designed our test scenarios using our usability starter kit templates.

The starter kit templates made sure our testing session was organized and our tests were consistent.

Rather than present our test plan and comprehensive observer notes to the team, we preferred to create a summary that grouped each users’ test step performance into a category that indicated confidence and overall success.

For each step, we categorized a user action to be:

• Immediate
• Some Thought
• Multiple Tries
• Failed

We then created color-coded tables of scenario steps and users to give a quick visual overview of smooth and troublesome points.

We used comments to call out interesting points from our observer notes.

We included three large comment notes to provide context and next steps:

• Rationale – Includes a brief summary of the test plan. Includes test hypotheses.
• Observations – States if hypotheses were supported or contradicted.
• Recommendations – Makes clear recommendations for next steps (if any). Should state areas that will be addressed but doesn’t necessarily define how.

I like how the template turned out. It provides a quick reference of intent and results, an intuitive visual overview, and qualitative details that balance the discrete categorization of users’ interactions.

Please try the template if it can be useful to you and please feel free to contribute changes or additions.

The previously mentioned blog post sets a cookie with a token that identifies the logged in user. I decided to simply use the user’s ID instead:

  def current_user
    return @current_user if defined?(@current_user)
 
    if Rails.env.test? && cookies[:test_user_id]
      @current_user = User.find(cookies[:test_user_id])
    end
  end

Allowing a production user to be automatically signed into the application just by having their user ID in a cookie is an exceedingly poor idea; thus, the check to only allow this type of login to work in the test environment.

Now all the Cucumber step needs to do is to set a cookie with the appropriate user ID:

  When /^I am signed in as "([^"]*)"$/ do |email|
    user_id = User.find_by_email!(email).id
    page.driver.browser.set_cookie(
      "test_user_id=#{user_id}; path=/; domain=localhost")
  end

Now when the next request is made from the test, the specified user will be set in the current_user call.

Notes

• This particular test suite is configured to access the web server using http://localhost:8888. I first tried setting the domain in the cookie to be 127.0.0.1, but it was not working. I am not sure what the default Capybara configuration is, but if you run into issues try both 127.0.0.1 and localhost as the domain in the cookie.
• In addition to the user ID I also need to fake out several more cookies that the application sets when a user signs in using the normal form. I ran into some trouble setting these until I escaped the values with CGI.escape:

  page.driver.browser.set_cookie(
    "#{key}=#{CGI.escape(value.to_s)}; path=/; domain=localhost")

• The version of capybara-webkit I am using is a little older; it appears that a new interface for setting/getting cookies has been added in the form of a cookies method on the Capybara::Driver::Webkit class. I haven’t used this interface yet so I can’t speak to how it may differ the approach described above.

In this talk he shares his knowledge about what “cloud” is and what the technology might mean to your business.

This overview might be old news for some but if you’re looking to get a big picture view of the cloud world, check out the video.

Next month Software GR will focus another of Grand Rapids’ own great development talent, Traction Software’s Andy Keller:

When should you reinvent the wheel?

When creating software, whether it be a small website or a large custom platform, you repeatedly face the build vs buy dilemma. Should you use raw sockets or a web framework that already speaks HTTP? Should you write javascript directly against the DOM or use a library like jQuery? Should you write a graphing library or find one on the web? Sometimes the answer seems obvious, but making the wrong decision can increase cost, time, complexity, maintenance and support.

In this talk I will start by framing the problem and will provide guidance for making the right decision while avoiding simple cliches like “don’t reinvent the wheel”. I will then go through specific examples from my experience working on a large mature codebase for a product that evolved considerably over more than 15 years. You’ll be surprised by some of our decisions and what we learned from them.

Check the Software GR website for the latest, and I’ll see you all there!

Though it may not be a real product, the code we write is real software: it has purpose and value, and it must work properly. Why would we treat it differently than anything else?

On the surface, it seems there are a few key differences in our approach to demo software as opposed to code we intend to launch into production. For starters, we might worry less about cross-platform support, server up-time, security and so on if such things provide no value to the demo. (Examples: selecting one specific smart phone for a mobile demo to reduce cross-device UI design and memory concerns, assuming a wifi network with preset addresses to avoid the need for a configuration screen.) We start to see how the phrase “must work properly” depends heavily on your definition of “proper,” on which we must carefully and continually maintain alignment with our customer.

But what we do build, we develop as we do everything else: working software that behaves as designed, without defects. We can’t ship a broken demo because we won’t get a second chance.

We’ve served our customers demo needs well with this careful balance of narrowing assumptions and quality software practices. In fact, a number of demos have lived long past their intended targets and taken on a life of their own. Different groups in the customer’s organization demo the technology to a different audience, managers show their managers, VPs show potential clients. (Very cool!)

But as the stakes go up, the software is in increasing danger of failure. Remember those carefully designed assumptions we made about environment and context? The new users might know very little about those. They’re in a new location, maybe using some newly introduced hardware, maybe running the app on their personal cell phone. You might expect a production app to weather the changes, but our demo app probably won’t. (Not very cool.)

So things start to break, and our original customers are getting stressful phone calls asking for help, and they ask for our help and we’re at a loss. We’re annoyed that our software is misbehaving, we’re upset that it’s impacting somebody important on the customer side, and we’re pissed off that we can’t seem to help.

Interesting puzzle, right? We did a good job, the software is a hit, and everyone wants to see it, but the longer this goes on, the worse things seem to get.

On the bright side, we have learned a few practical things that help us prepare for post-demo success, and the potential fall out:

• Deliver a single volume of all code, assets and tools related to the project, especially items produced by the customer’s team (if any)
• Include very good documentation, geared toward someone who might be attempting a ground-up rebuild of the project
• Automations: scripts and tools that enable quick build / deployment of the project

Even though the source code belongs in source control, and documents belong in a document management system or wiki, and the customer’s firmware images are their own to manage, having everything in one place provides a common frame of reference. On a phone call or emergency chat, we can refer back to this known good starting point, fast. Capturing the customer’s artifacts along side our own will save them the trouble of going back in time to find a match for what we gave them.

“Good documentation” doesn’t mean exhaustive, repetitive, templated documentation. Instead, strive for a README.txt that provides a list of simple steps to re-image a microprocessor, or upload a new config file, or access an error log. Write these docs expecting that the reader is sweating, hurrying and unfamiliar with Ruby, CoffeeScript, awk, and all the other crazy stuff you used to build and deploy the project.

We strive to automate the build and deployment steps for all our projects, and this extends to uploading code to embedded controllers or executing JAR files on remote tablet PCs. Why wouldn’t we share these tools with our customer? (We might need to add a few links to describe the installation and setup of our automation tools.)

These three items are hardly new—they’re part of any reasonable project. However, they can easily be overlooked in a proof-of-concept environment, where we’re making tradeoffs between traditional “production quality” and demo-time pragmatism. But the reality is that even the initial demo can present some pretty stressful challenges, and over-delivering on artifacts, documentation and automation can help even at this early stage.

The last observation I’ll make speaks directly to the anxiety we feel at the outset of a demo project, when experience warns us to resist tradeoffs that might lead to future instability: Remember not to second-guess the customer’s estimation of quality. Perhaps with the exception of the above three items, our customers must be trusted (and enabled) to make time-saving assumptions that can make the difference for their demo. With our help, they can retain this flexibility without sacrificing the quality of the product we’re building for them.

• Automobile manufacturing
• Banking
• Garbage collection
• Hardware sales
• Video rentals

Give up? Each of them, at one time, were nascent industries populated chiefly by small, local, mom & pop style businesses. Also in common: they are all now dominated by a small handful of mega corporations[1].

Is it possible that Atomic Object or the software industry in general could be headed down this same road?

Early in the 20^th century there were hundreds of carmakers throughout the western world, now the top 7 builders control nearly 90% of the market. Not that long ago there was a friendly neighborhood bank in nearly every neighborhood. After three decades of consolidation the likes of Bank of America, Chase & Citigroup now reign over almost every region of the US.  Waste Management, Home Depot & Blockbuster head the list of modern goliaths in the other businesses.

With some recent events here in Grand Rapids and in our industry the question around the office these days is how does this trend apply to the custom software industry, or does it at all?

According to one collator there are over 1600 custom software service companies in the United States. Over 60% of these companies had revenue of less than US$500,000, and about 85% with revenue below US$5,000,000. To put that in employee terms, nine out of ten firms in our industry employ fewer than 50 employees. We seem to still be in the “many small companies” stage of industry development.

The question of consolidation is an interesting subject at Atomic. We have been extremely cautious with the company’s growth plans. One of our core values is maintaining the culture of excellence that began with the formation of Atomic Object in 2001. We are convinced that keeping a manageable office size is one of the keys to this philosophy. Our concern about growing our Grand Rapids office much beyond our current size has been one of the motivations to looking at expanding to Detroit. It is inconceivable to most of us that we could be part of a company of hundreds or thousands and still be who we want to be.

Now, we think we’re getting pretty good at this innovation services game. And we think our culture and values have had as much to do with this as our technical prowess. Does this mean that the future of Atomic is sure to bring tempered or maybe no growth? In measurements limited to size, maybe it does. The bigger question is: is our industry headed the way of the mega corporation? I hope not. What do you think? Let me know in the comments.

Recently I came across a blog post about Snippets, a system that facilitates scalable, asynchronous feedback from employees to management. Every employee reflects on what he accomplished over the past week, and what he plans to do the following week. This email is sent to the team leader, direct manager, CEO or made open to everyone. From the iDoneThis post:

The Snippets process at any scale is a compelling productivity solution, and companies of all sizes have adopted it — some, like SV Angel, rich in Google DNA, do daily snippets. The process forces employees to reflect and to jot out a forward-looking plan for getting stuff done, all while requiring a minimal disruption in the employee’s actual work.

Setting aside time on a daily or weekly basis to reflect on the day is a powerful productivity hack. In The Progress Principle, Harvard Business School professor Teresa Amabile and Steven Kramer showed the counterintuitive conclusion that progress toward a meaningful goal is the #1 motivator for employees at work, not financial motivation or downward pressure. Professor Amabile prescribes 5 minutes per day of reflection, religiously protected by bosses, centered around the progress and the setbacks of the day. Simply put, employees connected to their work and its progress are happier and more productive.

Techniques like this arm leaders with information that makes them proud of their employees while intrinsically motivating employees.

Have you tried to implemented or participated in a program like this? If so, how effective did you find it?

He then moved onto how he kept things simple in his project and he decided to illustrate his point by using the example of NASA spending millions to develop a pen that worked in space whilst the Russians used a pencil.
This has been debunked many times, a quick visit to Snopes shows the story is false and that actually using a pencil would be dangerous with pieces of lead floating around the cabin.

( If you really want to buy a Space Pen you can. )

Back to the presentation and the presenter had now lost some credibility. With the Leprechauns of S/W Engineering being hunted down, be careful when doing a presentation, writing an article or a blog post that you don’t lazily use “common truths” that don’t actually stand up to scrutiny.

At Atomic Object, we’ve created a “Usability Test Starter Kit” to help bootstrap this planning process. The starter kit is a collection of documents with suggested procedures to follow including tried-and-true scheduling tactics, facilitator scripts, and a test plan overview document.

The kit has been very useful to us here, so we’re offering it as a free download.

The starter kit includes the following items:

• Sample Consent Form – a sample consent form for recording the test.
• Sample Facilitator Script – a pretty generic script for facilitating a usability test. Modify as necessary for your project’s particular needs.
• Sample Participant Script – includes the tasks that you will have your participants perform. you will need to extensively edit this document to reflect your particular testing goals and your project’s needs.
• Observer Notes – Notes sheet for observers with reminders about how and what to observe. Useful to hand out to all team members who will be observing the test.
• Notes On Usability Testing – General notes compiled by designers at Atomic Object. Good to review while working on a usability test plan.
• Sample Usability Testing Plan – A Usability Testing Plan is a good document to distribute to all team members (both internal and client.) It is the place where you include a general overview of the procedure that will be followed, as well as logistical information such as dates, time, location, and computer needs. Augment and modify the usability testing plan as necessary for your usability test’s needs.
• Checklist.txt – A checklist of things to do and remember before and during the test. Review each day you are prepping or running the tests.

We keep the starter kit in a Git repository so that it’s accessible to every team in the company. When a team is ready to conduct a usability test, they can copy the kit and modify each part of it to reflect the details of their particular project. Additionally, if a team tries out something new or has tips to share, they can add updated artifacts to the repo. That way, the kit evolves and grows along with our usability testing process.

Click here to download the Usability Testing Starter Kit.

I have a couple main reasons to avoid the preprocessor in .c files:

• It’s easy to add preprocessor statements, but hard to take them out. They are the ultimate quick fix, but the longer you use them, the more of them you’ll need to fix the next problem. Eventually they will take your code hostage, and the project descends into Preprocessor Hell — a place where it’s hard to determine what code is active and, if it is, what it does.
• I don’t normally have a compelling reason to put macro definitions inside .c files. Adding them there clutters up the more important aspects of my project. I end up putting these in one of my various header files.

I want to point out one good way to avoid using preprocessor statements in .c files when dealing with multiple platforms. First, here’s a program that uses the preprocessor to differentiate between platform implementations:

#include "interface.h"

void initialize(void)
{
  puts("Common Initialize\n");

#if   defined(PLATFORM_A)
  puts("Initialize A\n");
#elif defined(PLATFORM_B)
  puts("Initialize B\n");
#else
  #error "Invalid platform."
#endif
}

void do_stuff(void)
{
  puts("Common Do Stuff\n");

#if   defined(PLATFORM_A)
  puts("Do Stuff A\n");
#elif defined(PLATFORM_B)
  puts("Do Stuff B\n");
#else
  #error "Invalid platform."
#endif
}

void cleanup(void)
{
  puts("Common Cleanup\n");

#if   defined(PLATFORM_A)
  puts("Cleanup A\n");
#elif defined(PLATFORM_B)
  puts("Cleanup B\n");
#else
  #error "Invalid platform."
#endif
}

In this example we can see that there’s common code in each of the three functions, but there are also sections specific to each of PLATFORM_A and PLATFORM_B. It’s not too hard to see how this becomes unmanageable with more than 2 platforms or more than a few functions.

Instead of using conditionals in .c files, I propose using a single header file that defines all of the interfaces each platform must implement. It might look something like this:

#ifndef __INTERFACE__
#define __INTERFACE__

void initialize(void);
void do_stuff(void);
void cleanup(void);

#endif /* __INTERFACE__ */

Once we have this interface defined, we just need to implement it once for each different platform. Here’s the first implementation:

#include <stdio.h>
#include "common.h"
#include "interface.h"

void initialize(void)
{
  common_initialize();
  puts("Initialize A\n");
}

void do_stuff(void)
{
  common_do_stuff();
  puts("Do Stuff A\n");
}

void cleanup(void)
{
  common_cleanup();
  puts("Cleanup A\n");
}

… and here’s the second:

#include <stdio.h>
#include "common.h"
#include "interface.h"

void initialize(void)
{
  common_initialize();
  puts("Initialize B\n");
}

void do_stuff(void)
{
  common_do_stuff();
  puts("Do Stuff B\n");
}

void cleanup(void)
{
  common_cleanup();
  puts("Cleanup B\n");
}

Notice that the compiler will prevent us from compiling both implementations at once since the symbol names would clash. The preprocessor prevents this with a #error statement in the #else branch, but what if this piece was forgotten? I think it’s safer and cleaner to push this logic into the build system in order to simplify the code. This isn’t hard to do especially if each of the platforms have a directory for platform specific code.

Using a common interface with multiple platform implementations has several advantages:

• The compiler will help us catch missing portions or duplicate portions of the interface. A preprocessor-only implementation will not reliably help us catch these bugs.
• The C files don’t need special analysis to figure out what code is active and what code isn’t active. This makes the code more maintainable in the future.
• We completely avoid #ifdef hell.
• The common interface header file serves as a template for adding new platforms.
• Using different files for the platform-dependent code gives certain guarantees about independence. We can be confident we haven’t accidentally modified the code for the wrong platform.

I’ve put together a complete example of this anti-CPP-pattern in this GitHub gist. It consists of the following files:

• main.c – the entry point which calls all three of the functions
• common.h – some code that’s common to both platforms
• common.c – implementation of common.h
• interface.h – the interface file that defines the functions required by each platform
• platform_a.c – the implementation of the interface for Platform A
• platform_b.c – the implementation of the interface for Platform B
• bad_way.c – both platforms implemented in a single file using the preprocessor to select which code to include

If you have GCC installed and in your path…

You can build the code for Platform A by running:

gcc main.c common.c platform_a.c -o platform_a

Platform B can be built with:

gcc main.c common.c platform_b.c -o platform_b

I’ve found build system and architectural changes preferable to the use of preprocessor statements in .c files.

What other ways are there to avoid overusing the preprocessor?