Dan Adams

How to Work with Consultants Successfully

2013-01-01T12:56:00-05:00

A bit of advice on how to work successfully with a consultant (or consulting firm).

Get an inside look at their portfolio

Consultancies usually put up a public portfolio. This is the work they want you to see or the work they are allowed to show publicly. You want to see what they’ve done in the last year. This will give you best sense of their capabilities and the direction of the firm. They can often show recent work in private, if asked, that they can’t promote publicly.

Talk to the people who do the work

While I’m not a huge fan of actually interviewing every consultant as you would a full time hire (you really shouldn’t have to), talk to people at the firm that actually do the work (i.e. not the sales guy). Have a chat about your project and what it seems like to them. They should not only understand it quickly but be excited about it and have new ideas and suggestions.

Some firms will sell you their A team and give you the B (or C) squad. It’s not that common but it happens. These guys are jerks.

Keep the owner in the loop

You have every right as a client to give feedback to the person who cares the most: the owner. If you have a problem or feel like the project team isn’t pulling through get on the phone and make your concerns known in no uncertain terms.

This may sound harsh but it’s the best thing for both you and the firm. They can’t fix problems they don’t know exist. It’s easier to make it work with a firm you’ve already selected than finding another one.

Go local. Get them in-house.

The more closely you collaborate and the more often you talk the lower your risk. You’ll more quickly find issues and get things running smoothly. If possible, get a shop in town and have them live with you. They’ll spend less time with communications overhead (and more time on real work) and you can get updates from them directly instead of reading some sort of status report.

Have an out. Be protected.

Don’t leave yourself with all the risk hiring a consultant. One of the benefits not available with full-time hires is that consultants come with contracts or Statements of Work. This means either resource for hire or fixed bid (see below). Even in the case of team augmentation, encode something in the contract promising at least a minimum set of deliverables.

Don’t pay (everything) up front. Tie payment to deliverables or spread out over the schedule.

My experience hiring consultants

I’m a consultant. I’d like to think I’m one of the good ones. But I’ve also played this game from the other side.

I was the Head of Engineering in a product company creating a new product (essentially a startup from the inside). In order to serve both our old client / agency work and our new product development (while having no up-front capital investment) we had to get creative with engineering resources.

We worked with outside firms in Argentina, Connecticut, New York City, India, Vietnam, and elsewhere.

We worked with independent contractors / consultants in just as many places.

Eventually, we even set up an off-shore development team in Omsk, Russia.

In the first two cases (using contractors / consultancies) my success rate was maybe 25%. That’s rough. But once we found a person or shop that worked we set up a long-term relationship with them. In fact, one of the best contractors I ever worked with was just “some dude” out in Ohio with three kids getting his PhD. I never even met him.

These relationships were a valuable asset and complimented our sizable internal team. It allowed our business to react to resource needs without reducing internal staff.

Appendix: Consulting Pricing Models

(Is putting an appendix on a blog post a sign it’s too long? Oh, well.)

If you are unclear with how pricing works with a consultant, here’s the gist. Each model has it’s own risk and benefits and one is not clearly better than another.

Fixed Bid

You tell them what you want, they ask some questions, make some assumptions, and give you a document telling you what they will do and how much it costs. If you change your mind during the project, you get a change order (changing the contract and probably asking for more money). By signing the contract, you are in for the whole amount (assuming they deliver).

As a client, you get a promise of what they’ll deliver. In many ways the consultant holds the most risk here because if the project goes over budget (and they don’t manage the changes in cost) they are left eating the overage. Since they are holding the cost risk any fixed bid contract will include some degree of risk buffer.

These contracts are appropriate for projects that are fairly well defined and well bounded.

Staff Augmentation

You pay a certain rate by the person for as long as you have them. There is no document saying what they will deliver. There is no risk of going over budget for the consultant but the client has no guarantee what will be delivered. However, the client can change their mind every day if they wish. Also, the clients financial obligation is less than a fixed bid contract since the staff augmentation can more or less be stopped at any time.

This model is appropriate when the problem being solved isn’t well defined such as working with early stage startups.

Hybrid

While more of a contract detail, these two models can be combined such that the client gets a bit more guarantee of what will be delivered while at the same time not having to deal with change orders every week.

Identify a few high-level, critical deliverables and encode those in the contract. You can still change direction during the project although, if it’s a big enough change, you might have to do a change order.

Why Your Startup Shouldn't Hire Consultants

2012-12-30T11:13:00-05:00

Hired guns. Code mercenaries. Consultants.

Whether you are early stage or have an established product, bringing a consultant onto your startup can be a dicey prospect. Here are reasons not to and some things you may not have thought of.

While there is truth to all of these, there’s more to be considered. Reality is, many startups are successfully using consultancies (although they may not advertise it). In a world where good people are hard to hire, time to market is tight, and product quality is critical, hiring a consultant is not always the right thing to do. However, it’s also not always not either (if you’ll pardon the double negative).

Reason 1: They’re Expensive

If you need to hire a design / engineering consultant (in Boston, at least) you are likely looking at $100 - $250 per hour depending on the shop and what you need. That’s $4,000 - $10,000 per week per full time person. Assuming you had a full time hire that had a total cost of $150k per year (after taxes, benefits, overhead, etc) that’s around $72 / hour.

Ouch.

Of course, this assumes we are comparing cost for the same value which probably isn’t true. Not only might you be getting something better or different than you have internally but you don’t have the same costs associated. A consultant pays their own taxes, vacations, benefits, etc.

You usually don’t hire a consultant for a whole year. You bring them on for something specialized or because they offer something you don’t have in your internal team or can’t hire. They’ve got experience and skills that can prove to be invaluable:

Strategic insight. A general knowledge of the industry, best practices, and the ability to pinpoint the best technical or product direction.
They’re battle tested. They’ve been through the full project life cycle across different team sizes, contexts, and technologies. This adds crucial perspective that only comes by experience. Especially knowledge that only comes from previous failures.
They’re good. Maybe really good. That’s why they are “expensive” (usually). They’ve got the skills you need and can get things done quickly.
Consultants come with friends. Hiring a consultant from a consultancy means you’ve got a pool of similar resources you can draw from quickly without going through the hiring process for each one. Even for independent consultants, they often have a wider network to draw from when you need someone based on personal recommendation.
Consultants are easier to let go.

You may bring on a consultant simply to augment your team and add momentum. Add a consultant or two where it makes sense, crank for a while, and then scale down to a slower pace after the push.

In a perfect world, when you needed to grow your team you’d be able to hire passionate, invested people with the skills you need when you need them. That’s a fantasy. The reality is that hiring (both salary and consultant) is hard; it takes a lot of your time and involves significant risk.

Reason 2: They Walk Away with Knowledge

History matters in a startup. The reasons why things are what they are (both good and bad) are important. A consultant may come in, do some great work, and then walk out with all the good bits in their head. This is a legitimate risk for anyone hiring a consultant.

It’s not, however, a show stopper:

Integrate them in the team so there is knowledge sharing during the work. Make sure other people at least know, and ideally have worked on, their stuff. Do code reviews. Seriously, just do them.
Have them put together documentation during the course of the work (not at the last minute) and use it themselves.
Embed them in team discussions so they know why the team did what they did and vice-versa. The random, informal conversations are often the most valuable.

If this is a concern, don’t give a consultant the most important piece of your product and then have nobody else know about it. Add some redundancy or minimize risk by putting them on something else.

Reason 3: They’re Not Invested

Your core team is passionate and invested, you hope. (Let’s assume they are.) A consultant is usually seen (rightly) as an outsider who comes in, does something, and walks away with no strings attached. The assumption is that they won’t deliver the same quality or be as proactive at addressing problems as your core team.

Again, a legitimate concern.

Get a consultant with a good reputation, a good body of work, and seems like someone you can trust. Protect yourself by getting them as closely integrated with you and your team as possible; tight collaboration will quickly shed light on lurking concerns.

It’s incorrect to assume that consultants don’t have stake in your project. Consultants live and die by their portfolio and having happy clients is critical. Finding new clients is expensive and difficult. Happy clients come back for more work. Especially when working with startups, it’s foolish for me not to do everything I can to help them succeed.

Allow Me to Illustrate

Here are a few scenarios where bringing in a consultant may make a lot of sense.

Get Your Product Off the Ground

As a founder in an early stage startup, you face many challenges in getting your product off the ground. Furthermore, many founders have never designed a product, built a software platform from the ground up, hired a creative team, scaled anything, worked with big data, and might be working with emerging technologies such as mobile.

That’s a big, steaming pile of risk. Building the wrong thing, building it poorly, or taking too long can be a killer.

Bring in a (very) small team of experienced consultants who can not only build the technology but help you understand the product, the technical landscape, and build the right product. Furthermore, while working with the consultant you can be working on hiring that long-term team. The product gets built in the time needed and you get some breathing room to put your team in place.

Add Momentum or Features to an Existing Product

You’ve got your core team established and product off the ground. You have a well defined roadmap. Problem is, you simply don’t have the man power to get it all done in the time needed.

Bring in a handful of consultants, integrated them tightly into your team, and hit the ground running.

Bring in Some Expertise

This is the likely the most common case for a consultant; you need a special skill you don’t have in-house and doesn’t make sense to develop. Find a consultant that can do it but can also do a lot more; integrate them as much as possible and get as much out of them as you can. For instance, if you bring in a firm to do some mobile work get them to add value in other places such as touching the REST APIs, helping you create a mobile roadmap for after they are gone, or giving advice on to what degree your web apps need to be responsive.

Consultant != Contractor

I’m making an assumption here in the difference between a consultant and a contractor (this is my definition). Consultants (disclaimer: like me) are often brought on for their thoughts and experience in addition to getting the work done. Consultants may even challenge their clients with new ideas and approaches.

Contractors are brought on to perform a task, build a feature, do something specific.

Success or Horror?

Have you considered using a consultant at your startup? If you’ve used one, how was your experience?

5 Tips for Getting Your Startups Product Off The Ground

2012-12-28T21:27:00-05:00

For most of the past year, I’ve been embedded in Dogpatch Labs working with early stage startups, first ByteLight and then BlockAvenue, to create their core product and get them to the next level. Both faced the challenges of a pre-MVP product and small team. Here’s some of what’s involved, the challenges faced, and approaches to tackle them.

#1 Establish Vision, Create Focus

What defines success?

The answer to that question will change. Possibly often. You should ask it regularly and make sure your whole team understands the answer and the reasoning behind it. The answer will likely change based on how far out you look: what defines success for the next month will be different than 3 months or 12.

You may struggle to identify a single definition of success but it’s important that you do so (or attempt to as best as possible). Back up the goal with ways to measure it. Benchmark team progress regularly against it.

Give your team a clear sense of why you are there, how you are going to take over the world, and that they are expected to be a big part of that.

Some examples:

Being customer ready (if you sell a customer you can actually support them)
A product that demonstrates your direction strongly enough to incite new interest from press and investors
Getting enough app usage to demonstrate that, yes, the market really is there
Getting the “hockey stick”: non-linear growth in app usage, downloads, conversions, sales, or whatever else is the most important success metric for your app.
Generating enough revenue to get you bootstrapped

#2 Continuously Re-Define Your Product

While keeping your eye on what defines success, re-evaluate your product design. Evolve. Tweak. Change. Nothing is sacred. Get as much feedback and input from press, investors, peers, and users as possible. Then evaluate and digest it. Let it challenge your vision but don’t go chasing every idea or feature thrown at you. Resist all impulse to get lost in feature design. Stay focused on who your users are, what they want to do, and what you want them to do.

#3 Start Hiring. Now.

When hiring for a small team you want to hire heavy hitters who can help you drive towards the goal line. Unfortunately, so does every other company. Expect it to take at least three months to hire someone (especially the right someone). For engineers, designers, and front-end devs the market is shot. It’s been that way for a while and it’s only going to get worse.

Establish a hiring pipe (personal networks, word of mouth, meetups, even recruiters) and keep it full. Someone who’s not available (or interested) now might be a few months down the road. Don’t wait for positions to really open up; starting filling the pipe as if the position were open now (though I’m not advocating leading people on).

Even for a small team, grow them through mentoring. You want them stepping up to new challenges on a regular basis and taking ownership.

If time is against you, consider hiring a consultant (shameless plug). It’s by no means a silver bullet but the right consultant can add acceleration and experience where it’s sorely needed.

#4 Understand Your Team

My first priority with a new project is to get my bearings. To a frustrating extent, nearly everything that comes out of my mouth early on will be a question. I want to know the state of things and how they got that way. This extends far beyond technology.

Who are the founders? Who are the key influencers (founders or not)? What is the dynamic between them and the rest of the team? Who makes the decisions? Who really leads?
What technology is in place now? Why was it selected? What issues have they had with it so far?
What are the skills of the current team both technically and non-technically? Do they have good communication skills? Do they understand application architecture? Have they ever scaled anything or worked with large data sets? How do they handle conflict and stress?

Keep asking “why” until you really understand your context. If needed, take someone out to lunch or ask small questions in the break room. Tease out perspectives you can’t get in a group setting. Paradoxically, humans are what make software difficult and understanding the team is critical.

While this is especially true for an outsider it’s often true for the core team as well. The better a team understands itself the more it will function as a cohesive unit. A founder who understands his team can utilize their strengths while both protecting against and working on their weaknesses.

#5 Focus on Quality

Quality is the visible, tangible thing that gives your users, the press, and investors a perception of value. Make people want to use it and share it. Quality also shows that you’re serious and should be taken seriously.

Make it work. Make it beautiful. Make it fast.

Which factors have been important getting your product off the ground?

Mentoring & Apprenticeship for Software Engineers

2012-12-07T18:26:00-05:00

What we software engineers (and designers) do is very creative and, in general, best learned through experience. Computer science and color theory can be groked from a book but client communication, handling conflict, and other less tangible disciplines are gained in the trenches. Learning on your own is slow and error-prone; you can miss out on stuff or learn something wrong based on the project work you get or who you happen to work with.

I view the apprenticeship mentoring model for software engineers (as with a blacksmith, glass blower, ceramics or any of the high-skill, difficult to master traditional crafts) to be the best way of accelerating growth, increasing retention, and creating the kind team your organization really needs. What follows is my approach to such an apprenticeship model that works in both client services and product teams.

For what it’s worth, I have a good bit of experience with this: I was head of engineering during company growth from 25 to 50 (with a corresponding growth in revenues and projects). This meant going from an engineering team of 6 to an internal team of 15-20 and an off-shore team of about 10. It also required increasing the number of technical project leads from 1 (me) to 5 or 6 through direct mentoring. Those tech leads then themselves became mentors to the new hires as we grew. In my consulting work, I work with early stage startups, such as ByteLight and BlockAvenue, to design and execute hiring as well as plan and stabilize development teams for long-term product development.

Why Apprenticeship Makes Sense

Apprenticeship takes effort and dedication and does not come naturally to most individuals or organizations. It requires time and effort that may need to be justified:

It accelerates learning on the part of the apprentice in technical and non-technical skills including everything from code quality and language nuances to object design to client communication.
It enables molding junior folks into what you need them to be. With a strong mentor model, you can widen your hiring field since you can bring on candidates that can grow more quickly into something really useful to the business. Associates without mentoring can become a big hiring and project risk and kind of a “boat anchor” that weighs more senior folks down instead of providing valuable support and fresh thinking.
It challenges the mentor to grow as well. Mentoring grows technical, communication, and management skills beyond the limits of normal project work and open up opportunities for getting your people to act like owners.
It encourages dialog and thought around actively managing their careers. This is good for both the team and management; when growth happens from the bottom up it’s healthier and reduces the overhead load on management.

Success Factors

There are a few factors that heavily influence the success of mentoring.

Clearly Defined Roles & Goals

The mentor and the apprentice should both understand each others roles. It should be something verbally stated to remove any awkwardness or barriers. The mentor is responsible for providing not only support (general advice, answering questions, etc.) but also constructive criticism and recognition for good work. Both of these last two are critical to balance each other out and create a good relationship between mentor and apprentice. The apprentice is responsible to raise their hand when they need help and be pro-active about it. They should be actively looking for areas where they feel weak and pull in the mentor.

Mentoring needs to be clearly defined between the mentor and apprentice. The more ambiguity and awkwardness there is, the more that becomes a barrier to successful mentoring.

Mentoring should be seen as a largely voluntary responsibility. They need to be self-motivated and see themselves in the role.

Proximity

Proximity, or lack thereof, is a deal breaker. I prefer that mentor and apprentice be “attached at the hip”. It’s important that they feel very comfortable with each other and have a meaningful context that provides fodder for mentoring. They should talk often, even informally, so that there is a consistent dialog. Ideally the apprentice should sit near the mentor so that when a teaching moment arises the barrier to making that happen is as low as possible. Having to go find the mentor and interrupt them could be a high barrier, especially for junior folks.

They need to have something they both know so they can talk about it. Having to context switch from project work to a side project could be a significant barrier. Project work usually provides the best “fodder” for mentoring. People are already thinking about it and engaged. It naturally provides many “teaching moments” in a way that manufactured mentoring throughout side projects does not.

In either case, if you don’t make time to be working on things in pairs, the mentoring won’t really happen. Mentorship is prohibitively disruptive when it’s a constant interruption to “real” work and involves at least two mental context switches. It requires some dedication to a schedule to make it happen effectively.

This kind of thing can work without being spatially proximate. Pair programming through screenshares and audio chat can be an effective method of working through problems and passing along knowledge. You sometimes lose the non-verbal communications, i.e., being able to read the apprentice’s general level of frustration, but for many folks it can work. With remote team members working from home, knowing how to be effective as a mentor remotely can be challenging but critical. There are a lot of tools at your disposal to make this work; use every one of them.

Whether remote or not, make time for low-intensity touch points. Go grab a coffee or go out to lunch. This helps highlight issues you might be having that otherwise don’t get communicated.

Support for Mentors

Mentoring is not a natural thing for most tech leads. It’s a skill that needs to be developed. They should have someone that can provide support. This could be someone with some experience in it or even other mentors.

Acknowledgment that the mentoring investment is worth it needs to start at the top. Management support in the form of explicit goals, advice, time, and resources is critical.

Every Apprentice is Different

Apprentice experience level, skill level, interests, and personality and some of the factors requiring that each mentoring situation be customized to the mentor and apprentice in order to be most affective. For instance, with one apprentice they might be really strong code wise and need to focus on client skills and another might be totally different. It’s a balance of what that person needs and what the project context provides opportunity for.

Doing It

The Kickoff

Any apprenticeship should start with a structured meeting between the mentor, the apprentice, and whoever is heading up the apprenticeship program. The meeting should cover:

What mentoring is and why you are doing it (answer: because it makes you better, will make you more successful in your career, will help you enjoy and be more successful in your projects, and helps the business as it grows)
Where they are now in their skills and where they want to go
What everyone wants to get out of it
How it’s going to work: project set up, logistics, communication, going out to lunch together, etc

Mentors must know that the hour / day / week they would spend to do the best job of training / pairing with an apprentice is working towards some series of agreed upon goals. Knowing those goals would allow them to make the judgment call whether teaching or doing are the correct goals at any given point.

On the Same Project

In this model, mentor and apprentice are on the same project. This is usually a situation where the mentor is the project tech lead and delegates work. They sit near each other so the apprentice can ask questions and get help easily. The mentor frequently checks quality of work and provides feedback (for instance, code review a feature branch before merge).

The mentor should look for opportunities to push the apprentice outside their comfort zone using project work. Give them responsibility on something that is just outside their current abilities and has real consequences. This could be technical such as building a large feature, researching a technology, designing an object model or non-technical such as leading a client meeting, writing a spec, estimating something, or leading some aspect of the project process.

Challenges

This requires projects that can support both the mentor and the apprentice in terms of project budget and having work that can be affectively delegated.

One of the biggest challenges is in the staffing plan for projects. Not all projects will be a fit for their respective skill sets. Many teams don’t have a lot of flexibility in mixing and matching project teams for an ideal makeup and staff largely based on current availability. This could be a source of friction to the process and one you’ll need to be diligent about.

It also can change how you sell projects as you need to plan for mentorship hours and some inefficiencies, especially in the work done by the apprentice: all growth requires some degree of failure. Re-examine your task estimates for things that may be delegated to the apprentice.

Be careful to strike a balance between the cost of ramping up apprentice resources and the cost of delivering project features. Budgets may creep to account for “apprentice time” to a point where it effects project budget significantly if left unchecked. Crunch-time pressures also present a challenge to on-project apprenticeship.

One model is to attach the mentor / apprentice and then look for projects for the pair. The opposite approach is also possible in order to lower the resource challenges and budget waste; to find a project fit for the apprentice and then start mentorship with the tech lead on that project. I’m making a big assumption here that apprentices are not put on projects by themselves; having them on a project by themselves can be really risky.

On Different Projects

In this model, mentor and apprentice are on different projects but maintain a relationship across projects. They need something they can use as mentor-fodder:

The project the apprentice is on. This requires the mentor to stay up on it enough to look for opportunities to mentor with it.
A side project the apprentice is passionate about. The mentor would also have to agree that the side project provided the right opportunity for growth (it’s likely something that encourages technical growth).

Using a real project helps the apprentice be more passionate / engaged / successful in their project (which is more valuable to the business than a side project). It also provides scenarios and challenges to the apprentice that a side project doesn’t such as client communication and project process. Working on a side project requires time and energy both of which are usually limited during project work.

These two models could be mixed in order to provide more resourcing options. For instance, you could start in the first model and then, as resource allocation demands, change to the second model to keep up the relationship between mentor / apprentice.

Bootcamp style projects, a non-billable project geared towards getting new recruits ramped up on our practices, can work in the right context but require a fair bit of management, mentorship, and coordination outside of billable work. The “shadow” apprenticeship model on real billable work may be more practical for most organizations.

Resource Allocation & Project Pressures

Each project has it’s particulars and, just as you consider the situation for who would be the best fit as a team, consider whether it’s a fit for mentoring; the risk level and what you could get out of it. It could be very tough to mentor on a “heads down” project but there may be teaching opportunities there as well. In fact, a heads down project may be just the kind of catalyst for growth in a more senior person where it wouldn’t be a fit for apprenticeship of younger staff. The decision to go heads down and crank (and how to do and handle that) is, in itself, something a junior person could learn. Learning to manage project pace and intensity is a valuable skill.

Mentorship is a distraction. It is a context switch and that’s okay. Teaching and doing are very different goals and, at any given moment, one goal or the other should be the highest priority. If it’s crunch time, and delivering the product is the highest priority, you might put teaching on the back burner and focus on doing good work quickly. But at other times you would prioritize training and acknowledge the slower production time in favor of allowing the apprentice to work at his own pace.

The ratio of mentoring to project time could be estimated (and should be capped) but likely won’t be consistent. Mentoring with the context of a project (such as code reviews) can be a really effective method of upping quality, lowering risk, and lowing cost so it doesn’t always need to be seen as waste or overhead. For instance, code reviews are an excellent way of teaching while catching bugs before they make it into production code.

Mentoring is much less of a distraction if it’s in the context of normal project work. If two people are jogging together, it’s much more natural for one person to teach the other person better jogging form while they keep running. It would be highly disruptive if you were jogging and suddenly one of you said “now stop so I can show you how to do good pushups”.

Expect mentoring to need case-by-case consideration with resourcing to ensure that it’s done affectively without significantly negatively effecting project budget, quality, or overall success. Mentoring (and having junior folks in general) does take investment on the part of the company but that investment should be as known and controlled as possible.

The End Game: Make the Mentor Redundant

A mentor should, in most cases, be growing the apprentice in whatever way is necessary that the apprentice could eventually do their job. In many cases, this actually happens: the mentor starts as the project lead and by the end of the project the apprentice has taken the reins. A good example of this is a new project that has a heavy, green field development phase followed by a slower maintenance phase. The first provides an opportunity for the apprentice to lead the process, the product, and the technical machinery and possibly take the lead for the maintenance phase. This will be a challenge for them but is much simpler than green field development.

This isn’t always the case; you could also have an end game of an apprentice simply getting better at something specific. But, in general, you should be growing them to be well-rounded contributors. This typically is better for them and for the business.

Growth is Not Just for Apprentices

A well-rounded view of growth affords everyone opportunities for growth and improvement. For more senior folks, this means they don’t need apprenticeship but rather support in other ways from their peers and management. In many ways, growing senior folks is more difficult than apprenticeship since, as people grow, the challenges they need to encounter in order to keep them growing become very specific to that person.

Your Mileage May Vary

The form that mentorship takes (or should take) can vary significantly by the team and individual. What has and hasn’t worked for you? If you were without mentoring, is it something you could have benefited from?

Trello for Agile Development at BlockAvenue

2012-12-05T16:40:00-05:00

One of the my roles acting as interim-CTO at BlockAvenue is to manage a high velocity, agile development process. Trello is my new favorite tool when it comes to ticket management but it’s not without limitations. Here’s how we used Trello at BlockAvenue and some of the challenges working with it.

The Basics

Cards are arranged into buckets (Trello lists) each bucket representing how far in the future it’s cards will get done. The further out the bucket, the larger and less well-groomed it may be.

Lists are arranged left-to-right so that the most frequently used lists are on the first screen for most displays, the less used lists being to the right on the second screen. They also follow a logical progression of queued -> doing -> done.

Dec 2012: All of the priority cards for this month based on business priorities and other factors. This will map to multiple staging or production releases (even multiple releases each week) but all of the development in this month will be pulled from this bucket. Cards in this list are sorted roughly in order of priority. Most are assigned owners.
Jan 2013: Similar to the Dec list, this is for the following month but less well defined.
General Backlog: This list represents a larger backlog to be pulled from into the monthly lists. It contains all things that should get done at some point but didn’t make the cut. It can be thought of as the mid-term roadmap.
Future: A holding area for future ideas. When you have an idea, don’t be afraid to make a card for it. File it away so it doesn’t get lost. This is list is groomed the least often.

In addition to the time frame-based lists, there are a few special ones:

Inbox: All new cards go here. Cards are held until they can get triaged and moved somewhere else. This keeps the dev team sane and ensures the non-devs know their cards aren’t getting lost. It should be empty most of the time.
On Deck: Cards pulled from the current monthly milestone that are next up for development. You can think of this roughly as a weekly iteration list. This list should be fairly short and reviewed by the team every couple days (or even daily).
Doing: Cards pulled from On Deck that are being worked on.
Done: Completed cards. Note that we don’t have lists indicating the status of a done card (in testing, deployed, etc). This is only because we haven’t needed it but for some teams managing the work flow around Done cards is probably a good idea. For instance, you may need explicit design QA on a feature and there could be a list for those cards.

The Done list gets some special treatment: whenever a production release is made we rename the “Done” to something like “Dec 3, 2012 Release”, archive it, and create a new “Done” list. This captures for posterity what was released and allows anyone to know what’s done so far in the current release just by looking at the Done list. You may also want to tag the card with the git release tag.

Anatomy of a Good Card

Well-formed cards encourage getting the work done smoothly and accurately. While you may not need all of the following on each card, I find myself using using all of these to some degree overall.

Card Title, Tags, and Labels

Keep the title succinct. Put the long stuff in the card description. A long title will severly reduce how many cards you can see at once in your lists.
Tags for things like which users it affects, browser, platform, if it’s an epic or story, etc
Use labels to visually indicate traits of the card and allow card filtering
Work estimate. A good convention is “(5) Do something” especially when it’s supported by Trello Scrum.

Card Description

Be sure to write one unless the title, tags, and labels provide everything needed to get it done
Take full advantage of markdown. Include code snippets, samples of log files, bulleted lists, headers, etc.
Write a full spec for complex cards. Provide implementation hints / details.
Include reasons why the card is being done based on team discussion. This info tends to get lost and can be really valuable later.

Screenshots & Attachments

Don’t try to describe a bug with words if it’s visual. Just don’t. Take a screenshot (or multiple screenshots) with something like Skitch and attach it. Especially during design QA, designers can get across exactly what they’re are talking about.

For new features, attach images of the designs for reference even if the PSDs live in Dropbox. A side effect is the visual appeal it can add to your lists.

Checklist(s)

Use checklists to guide work and track detail progress.

Trello and git

We have two primary git branches: master (which always represents what’s on production) and development which is the current release under development and is frequently pushed to staging. Trivial and small cards can be done right on development but larger cards (or those involving multiple commits) get moved to their own feature branch. While not displayed prominently, Trello cards actually do have unique, auto-incrementing numbers:

All feature branches map back to a Trello card based on the card number (ex: 322_my_awesome_new_feature). You could also include the initials of the person that created the branch in a larger team.

Labels, Tags, and Finding Your Cards

Trello lets you easily filter by person or label. You only get six labels so use them wisely; it’s a pain to go back and change later. Here’s the labels we used:

Data, App, API, Admin: Major system components
Bug: Something that’s broken.
Needs Review: Needs clarification or discussion and isn’t ready to be worked on. When cards are pulled into On Deck none should have this label.

Keep in mind that one of the best thing about labels is that they are color coded making it good for visually distinguishing cards when the lists are unfiltered.

You will inevitably come up with ways you want to filter your cards that don’t fit owners, due dates, or labels. While Trello doesn’t have direct support for tags it does have a nice text search. It only searches the title and ignores any non-alphanumeric characters. With #sometag on the end of a card title you can see that a card is tagged and, as long as you pick a tag name that isn’t common to your card titles, you can filter by it.

Suggestions for tags:

Browser-specific: #ie9, #ff, #safari
User group: #dweller, #mover, #press
Card types: #epic, #story

Checklists Rock

Lists are awesome. Sometimes it seems my whole life is managed by making lists of things. Trello is no different. Tips on using checklists:

When grooming the backlog, create the checklist for a card to get a sense of what’s involved.
Use multiple checklists with custom titles to separate between components of a card (frontend, backend) or between roles (dev, design).
You can’t (yet) drag TODOs betweens checklists. Bummer.

Dealing with Long Lists

Lists can get long, especially if you attach images or use long card titles. Unfortunately, there isn’t a ‘send to top’ for cards but if you drop a card on a list quickly it will shoot to the bottom of the list. Try to keep your titles succinct or even reducing the browser font size as small as you can stand it. It’s a hack, but it works.

Card Estimates

This is, perhaps, the single biggest thing I miss in Trello; the ability to put a work estimate on a card and see estimate totals for each list. Even with a small backlog, tracking estimates can add much needed control to the process. this tool allows you to track estimates and graph them but it’s not a great solution: the estimates should be managed in Trello.

Trello Scrum looks promising although I don’t believe it does any kind of burn visualization.

Shortcuts

If you aren’t using Trello shortcuts, you should be. They will save you a massive amount of time when grooming the backlog.

Team Friction

We struggled with effectively using Trello to make the business stakeholders self-sufficient in answering the following:

How much is left and when will it get done?
Given our current team, how much can we get done in the next N weeks?

The following goes a long way to solving this:

Good team communication and regular review of the lists
Good card and list hygiene: well-formed cards and groomed lists
Date or goal-oriented lists
Card estimates and tracking team velocity

For Hackers: Card JSON and Trello API

Trello’s beauty is in it’s simplicity. When it doesn’t allow you to do something you always have the option of using the Trello API. Tucked away under the card details is a link to the card JSON:

When I Wouldn’t Use Trello

Trello is simple and necessarily limited. In a more complex project I could see easily outgrowing it. OnDemand JIRA with GreenHopper is a great alternative. Unlike Trello, it’s not free but it’s the Swiss Army knife of ticket tracking as far as I’m concerned. Between Trello and JIRA I have a hard time recommending anything else (having used most of the others).

An example where Trello might not fit is a software platform that needed to track things across versions of the software. A REST API with multiple versions could need maintenance fixes and releases against old versions. In JIRA, this is relatively trivial with version tracking. That’s not to say you couldn’t do it with Trello but it could get messy very quickly.

5-10x Speed Ups by Pipeling Multiple REDIS Commands in Ruby

2012-11-08T14:36:00-05:00

NOTE: This is now on github at https://github.com/mrdanadams/redis_pipeliner.

REDIS is fast. Really fast. And awesome. But that doesn’t mean you can get lazy with how you use it. Pipelining REDIS commands allows you to execute multiple commands in REDIS and return the results at once. I’ve seen this provide a 5x-10x speedup. He’s how to do it with the Ruby driver.

Why You Should Pipeline

(If your code isn’t performance sensitive the following is probably unnecessary.) When working with REDIS, look out for code blocks that look like this:

ask REDIS for something
do something with it
repeat

Depending on the number of calls you make, you could be paying a lot in over-the-wire and connection overhead (even within the same data center). A better model is to do something like this:

collect all your commands
send them to REDIS
unpack the result and do something with it

Even with REDIS being very, very fast and the server being close to the client, this can lead to significant improvements in speed. I’ve seen a handful of commands (< 10) pipelined to drop a 250ms page render to 50ms.

Get Your Pipe On

Here’s the general structure of using the Ruby driver to pipeline multiple REDIS commands. When you execute a command, rather than getting the result you get a Future object which you can ask for the result when it’s available.

Using Future comes with a few challenges:

If you are executing the command based on some context (such as a related object) you need that context when you get the result
Future doesn’t provide a nice way of waiting for the value to be realized or even checking if it has been

In this example, we’ll iterate through a number of objects each one needing a REDIS hash.

# we'll collect a number of Futures with their related context
# Let's pretend have a number of objects and need to get their associated data
cmds = []
objects = [] # we'll pretend this isn't empty

# Create the pipelined commands. Any REDIS commands executing in this block will return Futures rather than values
redis.pipelined do
  objects.each do |object|
    cmds << { future: redis.hgetall(object.key), object: object }
  end
end

# Now that we have our commands executing we need to wait for the values to come back
cmds.each do |c|
  # wait for each one to come back before proceeding. this is not ideal but simple and seems to work fine.
  while c[:future].value.is_a?(Redis::FutureNotReady)
    sleep(1.0 / 100.0)
  end

  value = c[:future].value
  object = c[:object]

  # do something with the REDIS return value and our context
  object.values = value
end

Improvements

You can see that the model here is pretty disjointed and makes for less-maintainable code. The problem is having to break your code up causing you to lose context. Something like this might make more sense (warning untested ruby pseudocode ahead):

Pipeliner.pipeline redis do |pipe|
  objects.each do |object|
    pipe.enqueue redis.hgetall(object.key) do |result|
      object.values = result
    end
  end
end

Pipeline could look like this:

class Pipeliner
  def initialize(redis)
    @redis = redis
    @cmds = []
  end

  def enqueue(future, &proc)
    @cmds << { future: future, callback: proc }
  end

  def wait
    @cmds.each do |c|
      while c[:future].value.is_a?(Redis::FutureNotReady)
        sleep(1.0 / 100.0)
      end

      c[:callback].call c[:future].value
    end
  end

  def self.pipeline(redis, &proc)
    # Executes callbacks with each result. This blocks.
    pipeliner = Pipeliner.new redis
    redis.pipelined do
      proc.call pipeliner
    end

    pipeliner.wait
  end
end

Embedding Backbone Templates in Rails with CoffeeScript

2012-10-12T12:30:00-04:00

Multiline string support in CoffeeScript offers a great way to embed your Backbone templates. In this approach, you can easily edit your templates while still taking advantage of JS minification, combination, and client-side caching.

Registering and caching templates

We’ll create a top-level object in our namespace to hold our templates which are cached for efficient use across many view instances.

# Our top-level namespace (which I'll just call NS for sample purposes) NS = @NS NS.Templates = templates: {} # empty object to cache compiled templates # gets a compiled template rendering by ID get: (id) -> @templates[id] # caches a new template register: (id, source) -> @templates[id] = _.template(source) # Register a template embedding the sources in a multi-line string NS.Templates.register "ourAwesomeTemplate", """ <div class="inner"> <h3><%= name %></h3> </div> """ NS.Templates.register "anotherAwesomeTemplate", """ <span><%= foo %></span> """

Using the templates

An example of using the template in a Backbone view:

NS = @NS NS.View.SomethingGreat = @Backbone.View.extend className:'my-awesome-thing' initialize: (options) -> # could also do this in render() @template = NS.Templates.get('ourAwesomeTemplate') this render: -> $(@el).html(@template(@model.toJSON())) this

In this case I’m registering and caching our templates on load. If we had more templates, or they were used less often, we could register them to be compiled on-demand which might be more efficient.

MongoHQ vs MongoLab: Selecting a Hosted MongoDB Provider

2012-09-26T10:19:00-04:00

In the course of building BlockAvenue, one of the decisions I made was whether to host our own MongoDB or use a hosted provider. Here’s the short tale of what I selected and the importance of top-tier customer service.

Self-hosted or managed hosting?

We were under intense deadline, had no resources to spend setting up or maintaining a MongoDB cluster, needed no heavy customizations, and needed the database up and running yesterday. Since the app was Heroku hosted, we also needed some control over which region it would be located in. The decision to use a hosted service was a no-brainer even if it meant higher costs for the EC2 instances in the short term. MongoHQ and MongoLab were clearly the top two choices. But which provider to use? And which size deployment?

A first-look at MongoHQ and MongoLab

My first impression comparing MongoHQ and MongoLab put me slightly in favor of MongoLab. In fact, we used the free plan on MongoLab for a short period (and I’ve used them for small stuff on other projects). As a customer walking in the door, I found the MongoLab pricing and info about their offering much clearer and more informative. Even when choosing a database, having clear pricing and product info is important and eye candy makes some difference. The MongoHQ page provides the basics on pricing but not much else.

With their dedicated plans, for instance, you know the pricing for a Large instance without a replica set ($525 / mo) and the Extra Large instance with replica set ($1,950 / mo). But what about starting with a single Extra Large instance and going to replica set later? How do I expand my cluster? What’s the process and costs involved?

The MongoLab documentation is much clearer and their technical architecture page (aka “What will I get?”) makes a lot of sense is and very well done. Overall, MongoLab was more informative and, frankly, better looking. Even when choosing a back end technology, visual goodness conveys a sense of quality.

Interaction with a real human

At this point, I’m on the fence and out of time; I need a deployment up, my data loaded, and to start setting up the production environment. I still have big questions about the specifics of the data we are handling; large amounts of geospatial data with very fast response times and a lot of queries.

I email 10gen asking to get on the phone with someone to ask a few questions about index structure, the amount of memory needed and overhead to plan for, and other performance concerns. Within 30 minutes I am on the phone with a 10gen engineer. Awesome. I could not have had a better experience with 10gen and would absolutely recommend people with non-trivial deployments consider a support contract or initial consultation.

Having my strategy worked out, I need to select a vendor and get the deployment up. I fire off emails to MongoHQ and MongoLab. Within 10 minutes, a real person with real experience and knowledge of MongoDB calls my cell (Chris from Birmingham). Chris is awesome; I explain our project particulars and he immediately comes back with solid questions and recommendations based on their experiences with other customers. 15 minutes on the phone and I am ready to pull the trigger. This was, without a doubt, one of the best customer experiences I’ve ever had (I sent him an email later saying as much).

I walk back to my desk, create my account, set up a new deployment, wait for the EC2 instances to come up (which took a few minutes), create my database, and am off and running. 30 minutes in and I have my instance with GBs of data and many millions of documents loaded and serving our Heroku-hosted app. Everything should be this easy. Rock on, MongoHQ.

I hear back from MongoLab several hours later (which, admittedly, isn’t that bad) but MongoHQ beat them to it and totally delighted me with their customer service. My production db was up and serving our app by the time MongoLab responded.

Living with MongoHQ

A few days later, we need to make the move to a replica set in preparation for go-live. I email support with specific questions about cost, process, time line, and scaling up / down as needed based on traffic (we knew we were going to get TechCrunch’d). Again, I have a response within minutes. A day or two later, on a Saturday, we circle back on this and are ready to make a decision. Email is sent to support giving them the go-ahead to both increase the instance size and create the replica set. Response was that they are on it but may not get to it by Monday. A few hours later, I’m delighted to see an email that the new cluster is up with the URLs for each server. Again, MongoHQ goes above expectations for customer support.

Once up and running, the clusters are largely self-service and we’ve had no problems so far. An admin panel shows the status of each node, connection and database info, and what’s happening on each instance now and in recent history. The old admin is a bit ugly and dated but the new admin (in alpha) is already awesome. It’s also responsive meaning it works well as a large view showing and as a mini dashboard. In fact, on launch day, I left it running in the corner of my second monitor all day to keep an eye on things.

Final thoughts

In the end, the offerings between MongoHQ and MongoLab may be marginally different, at least in terms of pricing and technology. However, MongoHQ support has so far proven to be top notch. For many of my clients without IT or dev ops resources, this makes the price increase over running their own MongoDB cluster on EC2 well worth it.

Creating a custom OpenLayers build by profiling usage

2012-08-18T12:45:00-04:00

OpenLayers is a great library for integrating maps especially when creating custom mapping interfaces. However, with great functionality can come great size. Weighing in at nearly 1MB for the full library, you should pair it down to only the modules used.

openlayers-instrumenter creates a custom OpenLayers build profile by instrumenting the JavaScript dynamically and tracking what’s used.

Instrument the OpenLayers JS

Load the instrumenter after OpenLayers but before using it:

<script src="lib/OpenLayers-2.12/lib/OpenLayers.js"></script>
<script src="lib/openlayers-instrumenter.js"></script>
<script src="you-app-code.js"></script>

Note: It’s not for production use so only include it while creating the build profile.

Load your page. About 2 seconds after page load, you’ll see something like this console.log’d:

[first]

[last]

[include]
OpenLayers/Map.js
OpenLayers/BaseTypes/Size.js
OpenLayers/BaseTypes/Bounds.js
OpenLayers/Util.js
OpenLayers/BaseTypes/Element.js
OpenLayers/Events.js
OpenLayers/Function.js
OpenLayers/Event.js
OpenLayers/String.js
OpenLayers/Control/Navigation.js
OpenLayers/Control/Zoom.js
OpenLayers/Control/ArgParser.js
OpenLayers/Control/Attribution.js
OpenLayers/Handler/Click.js
OpenLayers/Control/DragPan.js
OpenLayers/Control/ZoomBox.js
OpenLayers/Handler/Drag.js
OpenLayers/Handler/Box.js
OpenLayers/Handler/MouseWheel.js
OpenLayers/Control/PinchZoom.js
OpenLayers/Handler/Pinch.js
OpenLayers/Events/buttonclick.js
OpenLayers/Layer/WMS.js
OpenLayers/Layer/Vector.js
OpenLayers/Renderer/SVG.js
OpenLayers/StyleMap.js
OpenLayers/Style.js
OpenLayers/Projection.js
OpenLayers/Control/LayerSwitcher.js
OpenLayers/Lang.js
OpenLayers/Control/MousePosition.js
OpenLayers/Control/DrawFeature.js
OpenLayers/Handler/Point.js
OpenLayers/Handler/Path.js
OpenLayers/Handler/Polygon.js
OpenLayers/Handler/RegularPolygon.js
OpenLayers/BaseTypes/LonLat.js
OpenLayers/Animation.js
OpenLayers/BaseTypes/Pixel.js

[exclude]

This is the build profile used by OpenLayers to create a custom distribution for your app.

If you load new OpenLayers classes during page use, exercise those functions then call OLI.createProfile() in the console to dump the updated profile.

Using the OpenLayers build profile

Save the build profile into OpenLayers-2.12/build/custom.cfg. OpenLayers ships with a script to load the profile and create the distribution:

$ cd OpenLayers-2.12/build/
$ ./build.py custom

The compiled file is put in the same directory as OpenLayers.js.

The full build includes 261 files weighing in at whopping 942 KB (minified!). For most builds it will probably be reduced to about 60 files totaling 271 KB.

Room for improvement

A “reduced” build of nearly 300 KB minified is still quite large. I’ve used it in a Rails app targeted for the iPad and it worked great. Using a custom build made a noticable difference both in page load speed and responsivess when using the UI. However, I’d be surprised if we didn’t see a mapping microlibrary or two give OpenLayers a run for it’s money.

Migrating a WordPress custom theme to Octopress / Jekyll

2012-07-26T16:51:00-04:00

I decided to move from a VPS-hosted Wordpress with a custom theme to Octopress. Here’s how I did it, why, some things to watch out for, and a comparison of the experience.

Why are you hating on Wordpress?

I’m not. Wordpress is popular for good reason and I’ve used it for a while. However, it’s not without it’s warts and I was often left wanting. Here’s what I require from whatever is running my blog:

Creating posts should be easy
Hosting should be very cheap ($s / month or even free)
It should be fast. The output should be optimized for better user experience and SEO. Page load times should be low. Google PageSpeed rating should be > 90%.
I want to spend time authoring, not maintaining. I don’t want to think about if my blog is running or not. I certainly don’t want to spend my evening repairing a hacked Wordpress or fixing a failed upgrade.
I want to be able to customize the theme or functionality if needed.

It’s easy to get most of these with Wordpress but difficult to get all. For instance, you could get a cheap and fast hosting service but you may be limited in what you can customize (themes and plugins). Managed services that provide this often start in the range of $27 / mo.

A VPS with nice specs can be had for $6 / mo but you may still have performance issues in a shared environment. This also requires you to setup (and maintain) everything yourself.

Octopress gets much closer to meeting all the requirements:

Hosting static files is fast, secure, and cheap or even free (with github pages or the AWS free usage tier)
Once it’s up and running, it’s set and forget
Octopress themes are easy to customize and writing plugins for Jekyll or Liquid is easier than for Wordpress.

Optimization & performance

W3 Total Cache is a great plugin. It’s a one-stop-shop for best practices in client-side optimization. Despite this, getting performance on par with static files with a self-hosted Wordpress isn’t trivial.

Consider asset combination and minification, for instance. You need to know which scripts can be combined and which can’t (such as the lightbox library that, when combined, simply broke).

With a single download for each asset, using image sprites or data-uri images, the correct caching headers, and a CDN for static assets you’d think that would be enough. But it’s not. I found my VPS suffering odd latencies upwards of 500ms establishing a connection to the server. A simple test with ab proved failure to handle large traffic spikes. The VPS provided great RAM for the money but the Wordpress content caching ate that up quickly.

Let’s back up for a second. The vast majority of Wordpress blogs consist of static content. Rendering PHP or hitting a MySQL db on each view is foolish. Why not use something like this plugin to export all content to S3 or some other service for cheap and scalable hosting? I could have thrown varnish in the mix but that’s a lot of moving parts for rendering static content. It’s simply the wrong tool.

Sometimes the old tech works best. Simplify. For blogs, serving static HTML is an elegant and simply solution. Most of the features Wordpress provides are focused on the editorial side. Why let that dictate how the content is served?

Post editing

When editing posts in Wordpress I would often write in HTML mode due to bugs in the WYSIWYG editor. For instance, it would sometimes insert errant P tags or start inserting DIVs instead of Ps altogether. It makes a difference in the rendered markup and how the post displays. It also makes the content less semantic.

There are some nice features such as inserting and thumbnailing images. As you’ll see, however, a more minimalist approach using Octopress is even easier.

Trackbacks

I don’t really care about them. It was an interesting idea in the blog world for cross promotion but I care about real comments from real users. Trackbacks are spam at this point.

Remote / mobile posting

Not currently supported with Octopress. However, it’s conceivable to have a REST API talking to authoring apps that does a git clone / pull, authors a single post, and publishes. Log in with your github account and use your existing editors. It could certainly be done. I never did this anyway so I don’t miss it.

Octopress, unlike Wordpress, does allow offline authoring thanks to git.

Post scheduling

The editorial calendar plugin is great if you author posts ahead of time and want them auto-published on a schedule.

This is another instance where things often just don’t work. After one of the Wordpress upgrades I noticed my posts weren’t published as scheduled. Awesome. A little googling, cron jobs, and editing of PHP later it was working again. It’s a great feature, when it works (which is true of a lot in Wordpress).

Making the move

Wordpress custom theme to Octopress theme

Octopress ships with a default theme. At first glance, it feels like working with a Wordpress theme framework. Here, however, you copy the entire theme down and edit the files directly rather than overriding base files in the parent theme that can be upgraded later (essentially the way WP was before parent themes were introduced).

The default Octopress theme is well coded and nicely structured. Like any theme, it has it’s own markup structure and styles. Migrating from a custom theme (child theme based on the Thematic theme framework), I already had my own markup and CSS that, since I’m just moving the site, should ideally stay the same.

So that’s what I did.

I started with the default theme and stripped it down to something minimal enough to fit my needs (you can also copy in files later if needed). Grabbing the rendered HTML for the pages on my WP site I made the page markup conform to that. I was able to move the SCSS in without any changes at all.

Featured images

Some posts have a featured image at the top. I include the images with a specific CSS class so they can be targeted:

img featured /images/ios_xcode.jpg iOS universal frameworks with Xcode

Image thumbnails

Creating thumbnails in Wordpress is quite easy. With a little help, they are even easier in Octopress. I want to take a source image and say “insert this image, optimized, into my content and make it a certain size while keeping the aspect ratio”. Nothing I found did exactly that so I created a Jekyll plugin, jekyll-thumbnailer. Using it is quite simple:

thumbnail /path/to/local/image.png 50x50<

Compass sprites & image paths

If you want to use Compass sprites like this:

$sprites: sprite-map("sprites/*.png");
.foo a { background:sprite($sprites, foo-icon) no-repeat; }

The generated sprite image will be put in the source directory. That’s fine except the references in the CSS will look like /source/images/sprites-2t3h2t31h3.png. To reference the images at the correct path add this to config.rb:

http_generated_images_path = "/images"

exitwp

exitwp did the general conversion (including grabbing the post images) but it was pretty rough.

I have pretty standard markup and it did things like convert lists into multiple lists (also indented incorrectly)
I had to manually edit every single post
It put in weird spacing
It didn’t preserve the more tag thus killing all my excerpts
No support for images (or captions)

So I wouldn’t say migrating the content is exactly seamless. In fact, this took the longest.

Minor observations

A few observations after doing the migration:

I found broken and extra markup being generated by Wordpress
I eliminated a ton of extra CSS classes and ids from the markup to make it more minimal. Simply a side-effect of most theme frameworks.
The delay to regenerate files when editing can be really, really long. Isolating files can help with that. Also, you may have to get out of the habitual saving after each edit.
The default Octopress theme is well structured but verbose. I paired mine down to only a few files.
I didn’t care for the auto-capitalization
The syntax highlighting (including the styles in the default theme) is great

The final setup

Once set up, Octopress is pretty great. Author a new post:

rake new_post["My fancy new post"]

Run pow.cx to serve the files (you only need to do this once):

cd ~/.pow/
ln -s ~/path/to/my/octopress

Watch for changes:

rake watch

Once you are ready to publish:

rake generate
rake deploy

Don’t forget to commit your source files and push to origin as well:

git commit -a -m "i made some changes"
git push origin source

Octopress and Jekyll are both awesome. I’m sure improvements could be made and I’m excited to see (and help with) them in the future. Generating static sites is by no means new in the CMS world but it’s a great, simple alternative to Wordpress.

The sources for the blog are on github.

Round-up of iOS universal frameworks with Xcode

2012-04-18T13:38:39-04:00

If you are looking to share code between projects or distribute a 3rd party framework (such as a product API) a bit of googling will find you a solution. Or two. Or three. The solutions are all similar with some subtle differences. Here I’ve collected the best solutions I’ve found (going back to 2008) and which one worked well for me.

For the impatient, I recommend this iOS universal framework solution.

The problem: dynamic linked libraries, architectures and performance

All the system libraries for iOS are dynamically linked. This allows dynamic loading and sharing of libraries between applications for more efficient memory management. In order to simplify the handling of applications, this is not allowed for libraries shipped with an app even if two apps use the same library. These libraries must be statically linked. This is an issue simply because Xcode 4 does not directly support creating static iOS frameworks.

Additionally, libraries need to support multiple architectures: arm6 / arm7 on the devices and i386 when run in the simulator. Distributing a fat binary allows developers to drop the framework into their project but embedding the whole fat binary in the application should be avoided as it can substantially increase the size of the deployed app.

The developer experience is also important. For instance, if you are developing the framework in the context of an app that is using it, minimizing turn-around time for changes in the framework appearing in the app could be a big win (as it likely is for most).

Documented solutions

iOS-Framework by Jeff Verkoeyen

My preferred solution is by Jeff Verkoeyen (jverkoey). It’s an evolution on the older solutions and focuses on an easier, faster build process while maintaining a good integration experience for users and optimal deployment. It still has some improvements to be made:

A manual process. It’s easy, but not exactly a 1-step process. He’s documented it well enough that you could do it for a new project quickly if you couldn’t remember all the steps.
Bundling resources requires more work on the part of both the framework author and users. Code-only frameworks shouldn’t have to deal with this, luckily.

Blog post by Jonah Williams of Carbon Five

This post offers a well-written guide and explanation of the problem. However, it’s not as comprehensive as the others. It also uses the framework in a way that isn’t entirely representative of the way your users will. This increasing the risk that you might be missing something big when cutting a distribution. However, it’s a good guide and shares a lot of similarities with jverkoey’s approach.

iOS-Universal-Framework by Karl Stenerud

iOS-Universal-Framework offers a way of bending Xcode to your will so it will produce a static framework by introducing a new project template, possibly making life better if you need to do this a lot. The solution by jverkoey specifically improves on the method in a some marginal, yet important, ways such as resource handling and compile time. As with Chris Boyd, this method has made some people very happy.

See iOS-Universal-Library-Template for a similar project not focused on frameworks.

Blog post by db-in

As noted by jverkoey, the approach in this post is essentially the same as iOS-Universal-Framework but not as good.

Useful Links

An assortment of useful links related to this:

Older, probably totally out of date (but possibly informative):

abnqe: A better Netflix queue experience

2012-04-02T11:29:37-04:00

UPDATE: abnqe is now on github.

I’m a long-time Netflix customer. As someone who uses the website to watch movies and shows connected to a HTPC it’s become very clear that the website user experience is not a priority. Specifically, the instant watch queue management and ability to finding something to watch is just horrible. abnqe (A Better Netflix Queue Experience) is a small project to fix this.

The missing experience

The queue on Netflix, as used by instant queue customers, is an interesting example of an interface providing the basic functionality required in a way that is nearly useless to users. Well, that may be unfair. If you want to manage the order of physical DVDs that will be shipped to you in a specific order, it’s okay. However, for instant watching and finding something to watch from what is essentially my library of titles, it’s awful. The order of your shows simply doesn’t matter with instant as it did with shipping physical disks.

Consider this: I’m plop down on the couch after a long day, craft beer in hand and to watch something. Not sure what. But something. Fire up the instant queue. What do I get? I text list of all my items in no meaningful order without the ability to filter, sort or otherwise grok the 200+ items present. Ugh.

abnqe, as first released, is the bare minimum set of features I wanted: a nice UI for visually seeing my queue with the ability to instantly search titles. I’m already so much happier.

Future direction

I’ve got a long list of things I’d like to do to this thing. We’ll see what gets done. Here are some of the things I have in mind:

Filtering by type (TV / movies)
Basic queue management (removing, adding)
Get more detailed movie info
Adding movies to lists / tags (dude movies, wife movies, kids shows, documentaries, foreign flicks).
Filter by genre, rating, recently watched
Discovering new titles (without suggesting titles I’ve already seen; something that annoys me endlessly)
Rotten tomatoes ratings
See what’s trending with other users, added recently and expiring
Social sharing and recommendations from friends

Under the hood

abnqe is a Rails 3 app hosted on Heroku using OAuth and the Netflix REST API to grab account and movie info. The first version was basically a saturday project.

Who is this for?

I made this for me (and my wife and kid). It’s free to use. Use it if you want. Or don’t. But if you do, drop me a comment. How are you using it? Have any problems? Any suggestions for improving the experience?

Heroku Postgres: Shared, Dedicated or use Amazon RDS?

2012-03-28T12:20:44-04:00

Heroku shared databases can’t be beat for convenience or cost during development (assuming you are on Heroku already). What about when the app goes live? Here are some thoughts on whether the app should stay on a Heroku shared Postgres database, switch to a dedicated database or use something else entirely such as Amazon RDS.

Basic Considerations

We have a startup Rails app hosted on Heroku getting ready to push for an early alpha release. For such an app, what are the questions you should be asking?

How will you handle traffic spikes?
What determines growth in the size of the database?
Is the data read only/read mostly or does it contain quick growth data like page views and social activity?
How closely do costs need to be controlled?
How much traffic and data do you need to support?
How much maintenance will the solution cost and what staff is needed to support it?

For this app, the following were important to consider:

Since Heroku runs on EC2 they recommend (not surprisingly) that you grab a database plan where your entire DB can be in RAM. Dedicated plans range from 1.7 GB to 68 GB. Both our databases, being loaded with just testing data for alpha testing, were under 1 MB. That’s not very helpful for evaluating the size we needed.
We don’t store anything growth- or data-heavy in our DB: we don’t log analytics and all binary data is stored on S3. The data is going to grow with the number user accounts and related records. This is all very small, slow-growth data and even with a large number of new objects shouldn’t blow out the database size. All the search indexes are stored in WebSolr which will help keep the DB size down.
While it’s safer to go to a dedicated plan now, it’s starts at $200 in the door and we don’t appear to be anywhere near needing the storage or performance provided.

Heroku Database Migration Options

There are a few options for migrating databases if and when you want to go from shared to dedicated. Note that you should have a maintenance page while migrating your database, especially if using a manual migration method. During migration your database won’t accept any modifications (or if it does they will be lost).

Backup & Restore

This is the only option on Heroku for migrating from a shared to dedicated database. See PG Backups.

Works across all plans
Can be slower than other migration methods (especially with large databases) since you need to export and re-import the entire database and transfer it across the network doing so. However, it’s a pretty simple process and appears to be easy and fairly low risk.

Fast Changeover

In fast database changeover, you use followers (read-only slaves) or forking (snapshots) and then point the app at the new database. This isn’t an option for migrating from a shared to dedicated database or moving to or from the Heroku platform in general. However, it’s a good tool to know about.

Works for large databases better than a manual migration
Minimizes app downtime
Migrating shouldn’t require changes to the WebSolr index as the IDs should be the same

Use Something Else (like Amazon RDS)

Rather than staying on Heroku Postgres, you could switch to something external such as Amazon RDS (which is clearly MySQL and not Postgres if that’s an issue for you).

A switch from Postgres to MySQL might be an issue if you have lots of migrations and some use something database-specific
Heroku offers Postgres as a service (outside hosting apps)
Includes a nice admin panel and lots of scaling / migration features and support for scaling horizontally (if it should ever come to that)
We could host a Postgres install on EC2 but we now have to roll all that scalability stuff ourselves (which we could do). We’d probably consider using RDS rather than any self-run db cluster.
For us it’s mostly a matter of price and if the service Heroku provides is worth not doing it ourselves. Given that we don’t have a dedicated IT team for this project the time spent maintaining the cluster is an important factor.

At the point of putting out an alpha we didn’t even need the 15 MB database which is $15 / month. Again, the DB should grow in proportion to the number of actually accounts, etc none of which should grow quickly (unless we are actually getting a ton of usage). If we started tracking analytics of any kind this would change.

Getting Heroku Database Size

You can use heroku pg:info --remote=production to get the database size. For shared databases the output is not very interesting:

$ heroku pg:info --remote=production
=== SHARED_DATABASE (DATABASE_URL)
Data Size 648k
$ heroku pg:info --remote=staging
=== SHARED_DATABASE (DATABASE_URL)
Data Size 688k

Where We Left It: EC2 for Cost Reduction

If this app really takes off (like huge) we will likely move to EC2 / RDS to reduce cost. Again, this depends on the numbers (particularly how many staff we need to support an AWS deployment). This discussion has a good example of an experience comparing Heroku and RDS in the long-term:

The only way to achieve any concurrency in Heroku is to turn up dynos and workers. These are 5c/hour each ~ $36/month. The first dyno (but not the worker) is free. Therefore, if you want a concurrency of 4 dynos and 1 worker, you are looking at $144/month. We have found that we can easily achieve 4 times this concurrency on one small EC2 instance. You would want load balancing and failover, so assuming that you are going to use 2 reserved small EC2 on the east coast (Heroku is on the east coast too), that comes to 2 X ($227.50 per year + 3c/hour) ~ $81/month. This can be equivalent of approximately $576/month on Heroku.

Continuing with the $144/month figure for Heroku, shared database in Heroku is free, but the smallest dedicated instance is $200! Compare this with RDS, where an equivalent reserved multi-availability zone instance costs $455 yearly + 9.2c/hour ~ $104/month.

In other words, at a concurrency of 4 dynos and 1 worker with a free shared database, Heroku costs $144 a month, while Amazon with a potential of atleast 4 times that concurrency with failover for the database and the server costs a total of $81 + $104 = $185/month. At the full capacity of the EC2 machines with a dedicated database instance, Heroku will cost approximately $776/month while Amazon will continue to run at under $200.

…

The operational cost of maintaining the databases on Amazon is near zero, except for the initial setup, which can be super easy too if you have used it in the past. Web server operations can be a little more ongoing work, compared to zero for Heroku. However, once you have load balancing set up, and like in our case, capistrano + git based push system, you can be off and running at almost nil system administration time.

What considerations and decisions have you made regarding where your database lives?

Career story, trajectory and context

2012-03-21T14:13:08-04:00

An important aspect of good career management is understanding your career story. Where you came from, where are you now and where you are going. Knowing this is critical to maximizing your market value and communicating that value to others (such as in interviews).

Career Trajectory

Let’s assume you are considering buying a stock. The current price is $42 / share. Should you buy? I hope at this point you’re thinking “I have no idea!”. Exactly.

If I’m interviewing software engineers I need to know not just where you are now but where you’ve been and where you’re going. Consider the following profiles for potential candidates:

Middle-aged set in his ways who hasn’t changed in years
Middle-aged who just changed markets and is slightly behind but clearly has a passion and ability to learn
Middle-aged who is mature, rock solid and still has a passion for the craft
Junior with very little experience but incredible work ethic and hunger to grow
Mid-twenties “rock star” who’s smart with loads of talent but doesn’t have the hunger or humility to grow quickly

This list is by no means comprehensive. The point is to show that someone’s career trajectory is critical in understanding their real value. Are you a good investment? Or a liability?

Context is Critical

A subtlety of history and trajectory is context. Understanding the situations someone has been in and decisions they’ve made is incredibly informative. Great people can come from all sorts of backgrounds and crush whatever preconceptions you had about where rock stars come from and what really makes one.

For interviewers, the 5 Why’s is an excellent way of discovering someone’s depth. What was a big project you worked on or led? What were your responsibilities? What problems did you encounter and how did you solve them? Which design decisions did you make that you later discovered were wrong? How did you fix performance problems? What do you wish you had done? Dig down and find how they handle tough situations, how they think and their motivations.

Be introspective. Consider your own history. What do you thrive on? What do you hate doing? Where are your opportunities for improvement?

What every software engineer should know: your career is a business

2012-03-21T13:59:47-04:00

Your career is a business and you should manage it like one. There is a lot to being a great software engineer and therein lies the problem: a focus on the technical (which is important, clearly) but a neglect of business, communication, and management skills needed to be your own career advisor. Without these skills many great, passionate engineers find themselves at a disadvantage working for too little pay or enjoyment. Here are some tips to set you in the right direction managing your career effectively.

Business 101: Supply & Demand

You have something to offer. There is some demand out here for it. In working, you exchange your time and effort for money and other goodies. The more demand there is the more you get and vice versa.

The above is a basic supply and demand graph. Price tracks the demand line. If supply increases above demand prices drop. When the reverse happens price goes up. Like a good stock portfolio, your value (or price) over time should be increasing:

So what’s your value? What do you have to offer? Here are a few examples:

Technical expertise: You just know it better and deeper. Someone has a question about JavaScript hoisting? You the man.
Domain knowledge: You really get your business and it’s nuances.
Dependability: People know when they give you something it well get done. Really done. If you run into a weird bug you don’t give up; you pound on it until a solution is found.
Culture: You make the environment around you better. People like coming to work a little more when they work with you.
Leadership: You can get people going in the same direction and get things done that require team effort.
Creativity and insight: You understand what is really going on and can find novel solutions to the problems at hand.
Communication: You work well with designers, project managers, clients, etc and can resolve conflict without freaking out.

I’m sure you could come up with others. The critical point here is that a marketable skill set often extends way beyond the purely technical. Many recent graduates feel scammed by their Computer Science programs in being ill prepared for the “real world”.

Know Your Market(s)

First things first: what is your market?

Your first market is simply where you work. The world that is your coworkers and clients / customers is a market all its own with a specific slant of supply and demand. What are the unmet needs? How can you increase your demand by improving existing skills or getting new ones? Can you get ahead of the curve by acquiring skills soon to be in demand? In some cases you can even create (artificial) demand by introducing a new technology or service. Act like an owner and you’ll discover a number of opportunities to increase your value.

The wider market is harder to define. It could be in a specific technology (Rails or Java), a specific industry (healthcare, finance, retail), a certain kind of company culture (startups) or an odd niche (such a project manager specializing in bailing out projects in trouble: I actually know one of these). Within this market how do you stack up? Who are the leaders? What skills are most in demand?

Identifying and really understanding your markets can take a lot of thought and investigation but is well worth the effort. Once you’ve done this you can begin to strategically change your position. This means improving your current set of skills or changing your position altogether by picking up a new set.

Don’t Be a T-Rex: Awesome and Extinct

Being a “dinosaur” has little to do with age except the longer you work the more opportunity you have to let this happen. Being “dinosaured” is the result of being left with skills that have no demand in the market. For instance, focusing your skills on a niche may be a good idea as it could make you more specialized. If that market grows you could be a leader. However, if that market evaporates you may find yourself with something to sell and no buyers. Welcome to dinosaur-hood.

Talking Turkey

Talking money is rarely fun for engineers. It just feels dirty. Or selfish. I have one thing to say to this: get over it.

You may love what you do, the people you work with and your company (and that’s awesome). You may even work for a company that really takes care of you. But don’t forget for a second this is a business relationship; I assure you the business hasn’t.

This isn’t to say you shouldn’t love where you are (because I do and that’s always been important to me) or that there are company owners who are good people and try to do right by their people (because I know a few). The business has a bottom line and so should you. They write you a check (and provide benefits, vacation, etc) and get something in return. What that “something” is and how much it’s worth to them is the important bit.

By advocating “talking turkey” I don’t mean negotiation skills (although that’s important). I’m emphasizing being more conscious of your bottom line. Your company isn’t doing you a favor by paying you and you owe them nothing. You have a responsibility to yourself (and others that depend on you) to maximize your value.

Do you think about your career as a business? How do you manage your market value?

It's your company too, act like an owner

2012-03-06T14:58:51-05:00

Company ownership is a funny thing. Who really owns the company? Well, it’s probably the guy with risk in one pocket and a checkbook in the other. So your company isn’t exactly a co-op. You don’t have shares or equity. You aren’t a partner. Let’s assume you are at the ‘bottom’ of the company. I propose there is tremendous value in an ownership mentality: this is my company and I’m going to work to make it the kind of company I think it should be.

I am, without question, a small company person. Large companies, bureaucracy, and overly defined roles give me hives. I like open air, accountability, no place to hide. It’s like a small town: everyone knows what everyone else is up to.

In small companies (think consultancies, start-ups, small agencies) there simply isn’t room for depending on someone else to pick up the slack. When everyone collectively takes responsibility for what’s going on quality is higher, things get done, problems fixed.

The company gets a lot out of the individuals acting like owners. Is the reverse true? Yes. Even in a company of great people, there will always be unmet needs. What can you do to add value? How can you make yourself indispensable? Perhaps something can be done better. Perhaps something isn’t being done at all and should be. Step into the gap and become a leader. Find roles you can play in your team and in your company.

Act like an owner and you will find yourself taking ownership: first of roles, perhaps tools, then teams, departments, and even companies.

If, like me, you want to stay at the tech level and don’t want to pursue company ownership, the rule is still the same: what can I do to add value that nobody else is doing?

Changing Dropbox location for 1Password storage

2012-02-13T06:41:47-05:00

Dropbox is awesome. 1Password is awesome. When their powers combine… it’s awesome. Except if you need to change where 1Password stores it’s file in Dropbox. Here’s a simple way to change that.

From the mouth of 1Password support:

You have 1Password 3.9 which is from the Mac App Store. Apple requires (or will soon be requiring) all applications on the Mac App Store to conform to various Sandboxing rules. One of those rules is strict limitations on where the data files the application accesses are located.

In this case we allow 1Password to read the file 1Password.agilekeychain inside of ~/Dropbox/1Password/

So it will always prompt you to tell you that it is copying the file to that location and that the other one will remain in the prior location as a backup.

Long story short, you’ll have to keep your data file at ~/Dropbox/1Password/1Password.agilekeychain

I do apologize for the inconvenience though. Hopefully this helps.

Bummer. Here’s how to change it:

Open 1Password and go to 1Password > Preferences… > General
Disable using Dropbox. This will now store the files under /Users/yourname/Dropbox/Personal/…
Close 1Password
Open a terminal and follow the script below

Assuming you want to store your files in ~/Dropbox/Personal/1Password instead of ~/Dropbox/1Password (for instance, if you are using multiple Dropbox accounts on the same machine) do the following in a Terminal:

$ mv ~/Library/Containers/com.agilebits.onepassword-osx-helper/Data/Documents ~/Dropbox/Personal/1Password
$ ln -s ~/Dropbox/Personal/1Password ~/Library/Containers/com.agilebits.onepassword-osx-helper/Data/Documents

Enjoy.

Starting Emerging Business Tech meetup with first event on native / HTML5-based mobile apps

2012-02-03T06:23:15-05:00

I’m extremely excited to announce a new meetup, Emerging Business Technology, lead by myself and sponsored by Cantina Consulting. We’ve tried very hard to make this meetup one that provides a lot of value to it’s members, extremely high quality events and content, and satisfies a need not currently met by other meetups in the Boston area. We’ve already seen rapid growth and intense interest from a wide range of people working in technology.

From the meetup description:

This meetup provides engineers, practitioners and managers the context needed to evaluate and adopt rapidly evolving business technologies. Leave with an understanding of what the technology is, why it’s used, when to use it, and next steps to take. We’ll review use cases, processes, tools, and practices in a mini-conference format through short presentations, hands-on tutorials, Q&A; and code walkthroughs.

Topics may include Mobile app development, HTML5, responsive design, high-concurrency applications, interaction design, modern languages and frameworks, NoSQL databases, and mobile / tablet application design.

The first event, Native and HTML5-based mobile: strategies for mobile app development, has been scheduled and will be an awesome event. We’ve got 3 or 4 sessions by some awesome speakers planned, both from inside Cantina and from outside vendors. It’s a free event so check it out if you have any interest in strategies for developing mobile apps.

Beware using active_admin and Sunspot Rails gems together

2012-02-02T11:00:00-05:00

If you are using Active Admin and the Sunspot gem for Rails, beware: they conflict on the search method leading to some very confusing results.

Active Admin has a dependency on meta_search which provides a .search() method on Active Record classes. Sunspot attempts to provide the same method, aliased from solr_search, but only if the method does not already exist.

In short, searching can be done using solr_search() rather than search():

@search = Profile.solr_search do
  keywords params[:q]
  paginate page: params[:page], per_page: page_size
end

@results = @search.results

Using Sunspot, Websolr, and Solr on Heroku

2012-02-01T11:00:00-05:00

Having recently deployed a Rails app using Sunspot and Solr on Heroku, here are some tips for getting started, testing, searching, and deploying.

Getting the right gem

As noted in this post, getting the right gem for Websolr is important (yet confusing): the Heroku documentation is not consistent on which gem to use. In short, use the websolr-sunspot_rails gem which tracks the version of Sunspot needed by Websolr.

The following gems are used:

UPDATE (per Nick Zadrozny):

the docs at https://devcenter.heroku.com/articles/websolr are correct: You want to use Sunspot directly, not websolr-sunspot_rails. The only thing the devcenter document gets wrong right now is the version. The current version of Sunspot is 1.3.0. I’ll add that to my todo list ;)

The websolr-sunspot_rails gem was only needed for earlier versions of Sunspot in order to support the WEBSOLR_URL variable, which is supported natively in Sunspot as of its 1.2.0.

So all you need is gem 'sunspot_rails' in your Gemfile and you’re all set!

Configuration

config/sunspot.yml provides a base config file for development and production only. ENV['SOLR_URL'] and ENV['WEBSOLR_URL'] override any values in this file.

# Note: ENV['SOLR_URL'] and ENV['WEBSOLR_URL'] override any values here # The defaults are same as what's below so you only need to override as desired. # Removed production since that should never be used in heroku. # See Sunspot::Rails::Configuration.solr_url development: solr: hostname: localhost port: 8982 log_level: INFO test: solr: hostname: localhost port: 8981 log_level: WARNING

Starting Solr (locally)

Solr can be started (and stopped) locally with:

Testing

If using rspec the following can get you started:

RSpec.configure do |c| c.before :suite do module Sunspot def self.stub_session @sub_session ||= Sunspot::Rails::StubSessionProxy.new self.session end end end c.before :each do Sunspot.session = Sunspot.stub_session Sunspot.session = Sunspot.session.original_session if example.metadata[:solr] Sunspot.remove_all! end end

Your search spec may look like this:

describe 'Search' do def commit Sunspot.commit end def search(q) visit "/search?q=#{q}" end it 'does something interesting', :solr do Something.create! commit search 'foobar' end

The following allows Cucumber features not to explode:

# Solr faking. # see http://opensoul.org/blog/archives/2010/04/07/cucumber-and-sunspot/ # Note: we need to do more than this if we start doing search tests in cucumber $original_sunspot_session = Sunspot.session Before("~@search") do Sunspot.session = Sunspot::Rails::StubSessionProxy.new($original_sunspot_session) end

Searching and paginating

Perform the search in the controller:

class SearchController < ApplicationController def search page_size = 10 @search = Profile.solr_search do keywords params[:q] do boost_fields name: 10.0, user: 4.0 end with :include_search, true paginate page: params[:page], per_page: page_size end @results = @search.results @total = @search.total @paging = @total > page_size @start = (@search.current_page - 1) * page_size + 1 @end = [@start + page_size - 1, @total].min render (if @results.empty? then :no_results else :results end) end end

In the template show results and paging:

<h3 class="summary"><%= t('.your-search-header'), start: @start, end: @end, total: pluralize(@total, 'result') %></h3> <% @results.each do |p| %> <div class="result"></div> <% end %> <%= paginate @search, window: 1 %>