comment 0

8 Tips for Specs that Work

Here are some tips for creating more useful software specs that I gathered from my experience working on Delver.
Note: these are mostly relevant for specs that deal with user-facing features, but some apply in general.

Tell a story

Try to structure your document as a story that describes what the user does in the same sequence users are going to do it in the eventual system.
This conveys the experience better than just describing different pages and functions as standalone objects.

A picture is worth a thousand words

Include as many sketches of what the user sees instead of trying to describe it in many words. Things like interactions between elements and lists of fields are much clearer when looking at them the same way the user will.
Include in your spec a sketch of every significant UI “state” the user will go through (I use Balsamiq Mockups to create my sketches).

Use nested sections to create structure

Structuring your document with hierarchical sections creates structure and helps navigating your spec when reading it repeatedly. The spec will be used as a reference for a while. For the first read – the story-like narrative is best. For subsequent reads – the ability to jump to the relevant part is more useful.
If you’re using Word – use the built-in “Styles” feature for the titles of your sections. This also creates a handy navigation and allows you to quickly create a table of contents if you want:

Start new sections on a new page

It’s better to start a new section on a new page (Word shortcut ctrl-enter). This makes it very easy on the eyes when trying to read just a particular section:

Focus on what’s important by removing the tedious details

By nature, the spec contains a lot of details. You want the person who reads your spec to be able to grasp the main ideas and the UX flows while not being distracted by the details. Later, you want the details to be available for someone who’s interested in the details for reference, having already understood the flow and the main idea.
You can achieve this by moving details like form field lists, message lists and long if-else logic, out of the main story and into the appendix of the document.

Track changes

Add a changes table at the top of your document. In this table, list the date and main points of every change you make. Your spec will be adjusted during the review and development process. Documenting the main changes helps people who already read your spec once quickly understand what has changed since the last time they looked.

Use conventions

Like in code, it helps to have a few common conventions in all of your specs. Usages of this are a specific font/background color for literal text that is displayed to the user, developer notes and so on.
For example, I use the following standard for literal text:

Hey user, welcome to the website!

Don’t worry about DRY

If you’re a past/present hacker, you love the principle of DRY. Don’t worry about it as much when writing your specs. It’s ok to repeat yourself and describe the same thing twice in two different places if it helps the story-like nature of the spec and its clarity.

comment 0

Twitter API .Net Libraries Roundup

Out of the few Twitter API libraries for .net out there, the ones that seem most complete are: Twitterizer and TweetSharp.
I’ve been developing with both in the past couple of weeks and both are generally stable, complete and provide a clean one-per-one wrapper for the Twitter API methods. Which is great news ™.
TweetSharp currently does not support the Streaming API, which is a major drawback and the reason why I am sticking with Twitterizer for now.

I recommend using the latest 2.3.1 source code of Twitterizer.

Small but important note: Twitterizer’s team is not currently officially supporting the Streaming API, so to use it (in assembly Twitterizer2.Streaming) – comment out the following line at the end of TwitterStream.StartStream:


Otherwise – it will not work.

comment 0

Move Along, Nothing to See Here, I am Invisible!

Well, this is just too lame. This little window was just hanging around my desktop:

“Peculiar” I thought. But you can’t fool me. I dragged the edge of the window to *resize* the window (yes, just like they taught us):

An “Invisible Window”?! Oh, the lords of secrecy and the gods of international espionage: this is the shit!
Whoever coded this crap: you should poke your eyes out and hang yourself I hope there is a really good reason for this!

comment 0

Twitter API Rate Limiting

Reading, here are the major points:


  • Anonymous calls (things like users/show – get a user’s info) are limited to 150/hour, that’s 3,600/day. This limit is IP-based.
  • Authenticated calls (like a user’s home timeline) – 300/hour. Limit based on your app key.

Those rates are useful for a single-user app (something like TweetDeck), not useful for something like an app that crawls Twitter.
You can ask to be white-listed using this form:
If approved – you get 20,000 requests / hour. That’s more useful.

Search API

  • The rates are limited but to a higher rate than the REST API. The exact number is not disclosed.
  • Important to include a User Agent parameter, otherwise you will get a lower limit.

Streaming API

  • This is what you really need for high-volume Twitter polling. Gives you a sampling of all tweets based on optional filter you pass (e.g. user, keyword, location).
  • Have three access levels, based on what Twitter decides to give you: Spritzer (about 1% of everything), Gardenhose (10%) and Firehose (everything).
comment 0

5 Tips to Make the Most out of UsabilityHub

UsabilityHub is a great tool to quickly test your application UI and flows before writing a single line of code. Here are some tips from my own experience using this tool:

1 Use variations

When you’re testing various versions of the same design – use the “add variation” feature on an existing test instead of creating a new test. This will ensure that users who did the previous version of the test will not do the next version of the test. You don’t want the same people testing different version of a design because they’re already familiar with your design and so may be biased.

2 Start with 5 responses, then add

When publishing a test – start with the minimal amount of responses (that’s five). You can always add more later if you want. Once you asked for a larger number but don’t want to use them all (for example if you already identified a serious problem with the design after just a few responses) – the credits are deducted from your balance and you can’t stop a test and retrieve the unused credits.

3 Make your flow tests short

Don’t create flow tests longer than 5 steps. If you create longer tests – you will have very low response numbers on the steps that are closer to the end of the flow.
If you do have a flow that is longer than 5 steps – break it down into parts and use an explanation to set up the second part of the test.

4 Make your clickable areas forgiving

When creating flow tests – you can make your “hit zones” a bit larger than the actual button/link/area that the users need to click in the actual system. People are doing your tests quickly and you don’t want to see a “failure” just because the user clicked 5 pixels away from the button.

5 Consider the results carefully

Take the results with a grain of salt. Remember: this isn’t the real system and results will not exactly correspond to the eventual behavior you will see in the live system. Try to think through the results and identify what is a real conclusion about the design and what “problems” just stem from the fact that these are only mock designs.

comment 0


Yesterday I met with Omer Perchik who told me about his new startup Any.Do.
Honesty, I amazed with what he and his partner are doing. I am usually a critical person and I dismiss ideas very easily but I have to take my hat off for these guys. What is awesome about it is the combination of:

  • Great product idea
  • How smooth execution looks
  • Super solid business model
  • How crystal clear the vision is

Mark my words: Any.Do is going to be the best new product of 2011.
They’re looking, so if you are a developer based in Israel – I very strongly suggest you apply for a job right now.

comment 0

Product Management: Micro Focus

In the previous post I talked about clearly defining a product and communicating the definition to the whole team.

Once you have your product definition in place, there are two things that you control that can increase your chances to succeed:

  1. Quality of the team
  2. How well the work is aligned with the goals

We’re into product management, so now I’ll talk about Micro Focus, which is making sure that the everyday work of the whole team is actually promoting the stated goal of the company.

Micro Focus

No matter how hard you try, you’re going to have some “alignment inefficiency” – people working on something that doesn’t 100% help the goal. You are trying to minimize that. There are two reasons why this inefficiency exists:
First, most of the work (at least in the early, product development stage of the startup) is around details. The job of the programmer is very details intensive: you have to juggle a ton of various bits of knowledge in your head at the same time, while solving a very narrow problem in a very exact and accurate way. It is next to impossible to keep the “big picture” in your head the whole time. This is why pair programming proves so effective and why sometimes a seemingly “obvious” bug escapes the programmer’s attention.

Second, many of jobs that are likely to exist on your team have a universal and natural tendency to focus on things that aren’t helping your goal. For example:

  1. Programmers tend to over-engineer and over-do features because it’s often challenging, fun and speaks to their inner perfectionism. This is widely known as “gold plating”.
  2. Testers tend to concentrate on edge cases because their experience taught them this is where lots of nasty bugs go hiding.

The product manager is in a good position to not be distracted by all the above. “Attention to detail” is probably not a common strength with product managers anyway :)
Here are a few practical methods to improve Micro Focus:

  1. Communicate the focus clearly for every task. If you’re writing requirement documents that programmers work with – don’t just detail the specifics of the requirement. Describe the exact motivation and focus of what this task is trying to achieve. Instead of just saying “we need to have a search box” also say “we’re trying to allow people to easily find popular products based on brand, not based on exact model number”.
  2. Pay attention to the tendencies I mentioned above. Instead of saying “we’ll allow signing up using Facebook or Twitter” also mention that “there’s no special treatment of a user who signed up for our service then deleted her Facebook account” (for QA) and “there’s no need to allow merging two accounts of the same user” (for the gold-plating programmer).
  3. Have a moment in time where you talk face-to-face with the other team members and clearly explain what you’re trying to achieve, answer questions and think about the task together. A 15 minute chat with the developers and testers before starting a task can go a great way.
  4. Know what people are working on: walk the halls and enter some rooms. Show up at the DSM. Ask questions.
  5. Get to know the people. Different team members understand things differently, have different experiences and tendencies. Once you learn that, you know what and how much you should communicate to each.

Why Me?

So should the product manager be doing all this Micro Focusing? What’s with the team leaders? RND manager? CEO?
Of course you’re right. These people should be doing a lot of Micro Focusing, but believe it or not, the product manager is better positioned to do so.
Team leaders and RND manager – yes, they usually have a better ability to look at the bigger picture (that’s why they got “promoted” out of their cushy development job in the first place) but they have a very specific, detail-oriented job to do too: they need to manage people and tasks, think about resources, make execution efficient, develop process, take care of loose ends. They are trying to take a feature and make it happen as fast and well as possible. They can’t be thinking at every step of the way “am I doing the right thing?”. They just think “am I doing this thing in the best possible way?”
The CEO also has disadvantages: she needs to take care of things beyond the product. She may be a bit more distant from the day-to-day work. She may be in a different time zone, selling the product or looking for funding. She can definitely tell you whether you’re working on the right thing or not, but she just can’t be there in time to tell you that.

My company builds Delver – a website where you can discover great products that are interesting to you with the help of your friends. Check it out!

comment 0

Product Management: Focus The Team

This is the first in a series of posts on product management.

Two Kinds of Focus

In a startup project, the ability to focus is an absolute prerequisite of success. There are two kinds of focus here, I’ll call them “Macro” and “Micro”. Macro Focus means what is it exactly that your team is going to build. Micro Focus is making sure that every action and task a team member does is focused correctly.

Macro Focus

By definition, a startup is under financed and under staffed vs. an older company. Also, a startup will be targeting a market that is not yet established and not well defined, with a “consumer need” that is not proved. A startup simply cannot be “stretched” to work on a task that is not very focused and well defined, nor on a problem that is “old” enough to have pretty good solutions already (though, there are exceptions to that). The job of the product manager here is to:

  1. Decide on and define a problem the product will solve, and how it will solve it.
  2. Communicate this clearly and often to the team.
  3. Constantly make sure that what the team is working on indeed helps solving that problem as defined.

Defining a Problem and a Solution

How to find and decide on the “right” problem and solution is going to be a separate post. For now let’s see some examples of bad and good definitions.

Bad: We will solve online shopping by building a better e-commerce website

This is definitely a great market to target in terms of size and the solution is “right”, but it’s not nearly narrow enough for a startup and will require competing with great established players. Real life example: Cuil trying to build a better general web search engine.

Bad: We will build a social shopping site where you can ask questions and post video reviews

This is better in terms of finding a more unique problem: no product is a good solution to none of the above. However, this is still not focused. You’re actually working on two distinct problems (“get an answer” and “see a video review”). Chances are there’s a bunch of other teams working at this very moment on each of the above separately. You’re giving them an unfair advantage.
You may say that my example is very artificial and you’re right, but almost every startup I’ve been at or heard of is actually working on 3-4 distinct problems while thinking they’re only working on one.

Good: We will solve the problem of finding the right product by creating a site with short and high-quality video reviews

The problem is well defined and so is the solution. This can now be communicated to the team and also used as a litmus test to see if a particular task gets you closer to delivering the solution or not. Note: you are still far from guaranteed to be successful because you may be working on the wrong problem or the wrong solution, but at least you know exactly what you’re working on. This way – if you fail, you will fail faster and be able to pivot quicker. Both are good because they increase your chances of being successful in the long run.

Communicating Focus to the Team

Now that you’ve defined the focus of the product, you need to communicate it to the rest of the team. There are two goals you’re trying to achieve: alignment and motivation.
Why do you need alignment? Once you know the focus – you will be able to make all your decisions as product manager. You’ll also be able to constantly make sure that a given action and task are right for building the product. However, for any team that’s larger than 2-3 members, you won’t be able to keep up with everything people do. This is where you need alignment. You need to communicate the focus clearly and specifically enough for the other team members to be able to make the necessary focus-related decisions correctly, on their own, and on a daily basis. How many such decisions are there? I’d say that an average programmer makes hundreds decisions affected by the focus of your product every day. Needless to say, the programmer will make the decisions anyhow. Now imagine how far astray can the team go if the people on it do not clearly understand the focus. Some examples:

Do I need to invest time in creating a smooth rating widget for the video display?

Definitely, because our solution is showing quality video reviews and how are we going to know which ones are good if people don’t rate the videos they watch?

Do we need to build a great commenting functionality on the video display?
Probably no (not now anyway), because we’re not solving the problem by letting people read others’ written opinions about products.

The second goal of communicating focus is motivation. When people know exactly what they’re working on they’re better motivated because:

  1. It’s easy to know where they stand in terms of reaching the goal – this is a powerful motivator. Just think about running up hill and not seeing where the hill ends compared to finally seeing the finish line.
  2. It’s easy to empathize with the user’s problem as opposed to working on something that is generic and “faceless”.
  3. Team members can decide for themselves whether the product is something they believe is going to be successful and whether they even want to be working on it.

The last point is worth an elaboration:
The world is full of good professionals who don’t really care what they’re working on. They are motivated by other things: getting paid, technical challenge, nice work environment. There is nothing wrong with that. However, in a startup, you should try very hard to have a different type of people on board. You want to have the people who truly believe in the exact focused problem and solution you’ll be working on. That’s because you will get into hard times where the progress will be slow and money will be running out. That’s where the extra belief and motivation of those team members who decided for themselves that the product is “right” to work on will come in handy. Almost every successful startup story mentions how there was this rough moment where it looked like the company is going under but somehow miraculously held on. Every time it was because the team members personally believed in what they were doing.

In the next post I’ll talk about “Micro” focus.

My company builds Delver – a website where you can discover great products that are interesting to you with the help of your friends. Check it out!