13 Ways to Talk to a Programmer

[With apologies to Wallace Stevens.] If you decide to venture beyond talking about how your news organization’s site should work into actually changing how it does work, there’s one essential skill you’ll have to learn: how to talk to a programmer.

Most nonprogrammers have no idea how to communicate their idea for a new feature or a whole new website in a way that’s going to be useful to the person who’s actually building that site. Here are thirteen tips to get you started on the road to fluency:

1. Learn how to write a spec. One of the biggest frustrations for a coder is working up a version of something and then hearing from you, “No, no, that’s not what I meant.” Writing down what you want — in detail, and feature by feature — is a mark of your respect for a coder. Having a written spec will let you work with a better class of coder, and, more importantly, it will force you to really think through your idea. Don’t use anybody’s preprinted form for this, but do read Painless Functional Specifications, a series of four short essays from noted software guru Joel Spolsky on how and why to write up your ideas.
2. View and Do. Once you start writing up your idea, you might find that the end result feels distressingly like an unrelated laundry list of features. One of the best ways to give your list of features some structure is to break them out by user role, and then, by asking, what can the user view and do on this page?
3. Clip, Clip, Clip. Use a screen capture program to let you make images of parts of websites you like. Programs like SnagIt for the PC and Snapz Pro for the Mac let you draw a box around anything on your screen and save it as an image.
4. The World’s Worst Wireframe. You probably think wireframes are something done only by people with very fashionable glasses and the word “designer” on their business card, and you’d be right. You’re not going to make wireframes, you’re going to make Very Bad Wireframes. You should be able to draw a picture of what a page or a dialog box looks like on your site, and these should be included with your spec. You can do these by hand, but you’d probably get a lot out of using a wireframing tool like AxureRP for Windows or OmniGraffle for the Mac. These are like specialty drawing tools where the clip art contains things you’d expect to see on a web page or in an application.
5. Self-Enclosed. Your idea must have a beginning and an end. If you start hearing yourself say the word “platform” and begin to believe that it could do an infinite number of things, stop and take two weeks off.
6. Modest. Keep your initial projects small. A project that adds one feature to pages on your site — say, a thumbs-up, thumbs-down rating for restaurant reviews or articles — is bigger than you think.
7. Code Freeze. Once your coder starts working, resist the temptation to add more features.
8. Land of the Mashups. One good place to get ideas is the list of APIs at Programmableweb.com. API is short for Application Programming Interface. Many sites on the web have APIs that let you pull data or even features from another site on the web onto your site. If your site is commercial, be sure to read the terms of use carefully; if you want to try something as an experiment, contact the site whose API you plan to use and ask if you can use their service on a limited basis while you’re experimenting.
9. Communicating Without Calendars. Scheduling meetings is a pain. Decide up front on a fixed weekly time to talk with your coder and stick to it, even if you talk between meetings.
10. What’s Interesting to a Coder? Ask your coder what tools and programming languages interest them; ask about any side projects or previous projects they’ve done, even if they don’t seem related. Whenever possible, let your coder use tools and techniques that are of interest to them within the context of your project.
11. Code on the cutting room floor. Most of what a coder produces in their lifetime will end up being thrown away, either because poorly organized projects mean they write code that is never released, or code that is used is eventually decommissioned. Think about how you’d feel about this situation. If possible, consider licensing terms that allow the coder some degree of continuing ownership over what they wrote, as long as it doesn’t interfere with your project or your business.
12. How it works vs. how it looks. In general, the person who will define whether your sidebar boxes have rounded corners, or whether you should use a light or dark background on the page is not the same person as the coder. Talking about the “look” of your application will waste a coder’s time if that’s not part of their job. As part of writing your spec and making your wireframes, you should be able to keep how your site or app looks and what it does separate in your own mind.
13. Hello, World! Being able to write even the simplest program in virtually any language will help you understand and communicate with a coder better. Pick up Chris Pine’s short and delightful Learn How to Program and try a few of the exercises for yourself.