| Once you've assembled a team and defined the problem your solving, you're ready to sit down and design the application. But the actual process of software development varies widely from company to company. Some are very structured, following rigid rules and producing formal documentation. Others (usually smaller, younger companies) seem to make it up as they go along. But most teams center the initial development process (sometimes called the definition phase) around creating two or sometimes three documents. Software documentation: The functional specification also known as the "product definition" or the "requirements document" is written by the producer or product manager, while the technical specification is written by the lead engineer. Sometimes a design specification is produced as well; it would come, of course, from the designer. But the documents themselves don't matter as much as the decisions they document. So rather than just pass documents back and forth or present dueling PowerPoint presentations the best approach is to just sit down and talk through what, exactly, this application will do. Get your (small) team together, sit down in a room for a few hours, or a few days, or even a few weeks and hammer out the product definition together. "The key is to sit down with the engineer, and go through all the details," says Noah Mercer. "Define everything in as much detail as you possibly can. And then write it down." One way to help things along is to break out of formal structures. Product managers are often asked to write "specs" (or specifications) for the application. But they don't know where to get started, or what, exactly, is expected of them. To jumpstart the process, Jeffrey Veen discards the spec altogether. "I just have someone tell me a story about how the application should work," he says. "Because people know how to tell stories. They don't know how to write specifications." documenting how it works When developing an application, you should produce two parallel documents, which together outline the task at hand: Functional Specification | Technical Specification |
|---|
a.k.a. "product definition" or requirements document. | a.k.a. "design document." | Explains what the application does, and who it's for. | Explains how the application works from a technical standpoint. | Authored by producer, with consultation of lead programmer and designer/usability expert. | Authored by lead programmer. Uses the functional spec as a guide. |
|
the functional specification Also known as the product definition or the requirements document, the functional specification offers a detailed description of what the product will do and how it will work, from a user perspective. These functional diagrams shouldn't be confused, however, with the final design. The functional spec should include High-level description of the product, covering what it is and who will use it Description of users, with any needed detail Task-by-task description of functionality Screen-by-screen diagrams, showing visible functionality Flow chart, diagramming the user path Complete listing of input fields, with acceptable variables Potential user errors, and how they'll be handled
To produce the functional spec, the team often starts off with a high-level overview of the product's purpose and intended audience. They then walk through the program task by task, following the basic flow of the user experience and detailing all the functionality. Many teams find it helpful to move page by page (or screen by screen) through the application. Some document everything in writing, some create paper prototypes, and others actually build HTML mock-ups on the fly, so they have a clickable prototype when they're done. In any case, they would account for all the decision points users have, the input fields with which they'll be presented, and all the variables they'll accept. Ideally, they'll anticipate every possible user error and decide how each will be handled. The functional spec can be delivered primarily in writing, but it's most effective when accompanied by flow charts diagraming the user's path through the tool and schematics showing roughly how the features will appear on the web page. These elements are sometimes broken off into a separate design spec, and in some cases they replace the written spec altogether. It's important to note that these functional diagrams shouldn't be confused with the final design. Their purpose is to visualize functionality and express the relationships between different features. They may be produced by the designer, who will later create the actual interface, or they may be handed off to visual designers, who will collaborate with the team on the final product. the technical specification Also known as the design document and often called the "tech spec," the technical specification outlines the product's high-level technical architecture and provides details on how it will be executed. Its intended audience is the other members of the technical team, including programmers, QA specialists, and the company's technical director. It's also important to future members of the technical team, as it provides both an outline for understanding the product's structure and a rationale for choices made. Producers should note perhaps with relief that this document isn't for them. They probably won't understand it at all. And that's okay. That's why you created the functional spec. As long you have a functional spec in place, you can leave the engineering team to translate it into a working product. For more on writing technical specs, try "Anatomy of a Design Document" by Tim Ryan: http://www.gamasutra.com/features/19991019/ryan_01.htm. lesson from the trenches: how to work with engineers  "The key thing is to sit down with the engineer and go through all the details. Then write it down." Noah Mercer  "Engineers are in love with their invention. If you're interested in it, they'll be more likely to trust you." Indi Young One of the biggest challenges of web development is bridging the gap between technical and non-technical team members. Here's a guide to get you started. Bring them in early. This applies to all collaborative projects, and holds true here: You should consult engineers early in the development process, when the product is still being defined. If you don't, you risk both charting an impossible course and alienating your engineer. Present a specific problem to be solved. Engineers are natural-born problem-solvers. They usually produce their best work when presented with a problem to solve (rather than a solution to implement). Collaborate, don't dictate. It takes at least two minds to create a web application. You may understand the user problem you're solving, but the engineer understands the technical problem. You need each other. In order to produce a successful site, you must find a way to work collaboratively. (See how to encourage collaboration, p. 330.) Be clear about what you need. You must have a clear mutual understanding of what a requested feature has to do and what it doesn't have to do. So don't ask for vague or ill-defined features. Go over every aspect of the product in painstaking detail, in order to avoid misunderstanding. "The key thing to do is to sit down with the engineer and go through all the details," says Noah Mercer. "Define everything in as much detail as you possibly can. And then write it down." Be decisive. Think through needs and priorities before development starts. Nothing causes engineers more pain than "flip-flop" project managers who can't make up their minds, says Jim Morris. A change in plans usually means you've wasted their time and energy. "Every feature change feels like a stab of a knife to an engineer." Prioritize. Every new feature added to the list pulls resources. Don't request a new feature without explaining where it falls in the priority list. Be explicit about what's most important, and what should be completed first. Set clear goals for the project. The better you articulate the goals, the more effective your engineers can be. "If it's ingrained in them what the goals of the project are then they have a measure by which to make some of the micro-decisions, even when you're not around," says Greg Dotson. "Then they don't have to involve you in every micro-decision, and they feel empowered." Think in versions. The first released version of your application will not be the last. Web software development involves constant iteration, so you have to get out of the mindset of producing a grand, perfectly executed product all at once. Ask questions. As producer or designer, you need not understand the intricacies of the site's system architecture or object model, but you do need to understand what's going on. "You have to ask questions," says Lance McDaniel. "Non-technical people get thrown off in technical conversations by acronyms and jargon. But once you get caught up on the terms, the conversation is not unreasonable to follow." And there's another benefit to asking questions. "People like to be thought of as experts," says Greg Dotson. "So asking lots of questions that appeal to their knowledge and listening to the answers are good keys to opening up a dialogue and building rapport." Learn the language. As intrepid travelers always learn: It helps to speak the language. Or at least understand a few words. Brush up on the terms you hear engineers throw around. (You can look up any word on Google and have a definition in seconds.) But don't just throw buzzwords around make sure you understand words before using them yourself. Ask about implications. It's hard for non-engineers to know whether a given task is easy or difficult. So it's important to ask: "How much time will this take? Will it jeopardize other projects?" Cate Corcoran, former Director of Online Communications for PeoplePC, says, "One thing I would do is just admit that I didn't understand the magnitude of certain requests. It's almost like a two-step request process. First I'd ask, 'If I requested this, what would it mean?' Then I'd say, 'OK, I'm requesting it.' Or, 'OK, I'm not requesting it.'" Show some interest. Many engineers hold their projects near and dear to their hearts. So showing a sincere and informed interest in their work can go a long way toward building trust. "Engineers are in love with their invention," says Indi Young. "There's a real part of them in there. They know how it was born. They know why they brought it to life. They know the little jokes they put in it. They know where it's going to go next. They have goals for this thing. This is just like a child, really. So if you're interested in it, and you ask smart questions about it, then they're going to want to talk to you. They'll be more likely to trust you." Convince them it was their idea. "There's a lot of judo involved in working with engineers." said Jeffrey Veen, author of The Art & Science of Web Design. "You know, you use the force of your attacker against them." He explains: "Last week, I spent, literally, an hour going in this huge circle with an engineer until he decided to do the thing I wanted to do in the first place... That's the judo you use with engineers. Let them decide to do the right thing, by directing them toward it." "Of course, designers are just as bad," he laughs. "They're both equally stubborn." Find a good mentor. It's hard to find an engineer who can patiently explain technical concepts in non-technical terms. When you find such a person, don't let them go! Get them on your team whenever possible. And even if they aren't working on the same project (or in the same company), hold on to them! Ask them questions; take them to meetings with you; remember their birthdays; buy them coffee. They are very, very important to your success. Don't forget to say thank you. "It's really important to give people positive feedback, and to thank them for the things they do," says Cate Corcoran. "A lot of times, engineers will act like they don't need your praise. When you thank them profusely for working all weekend, they'll act like you're a dork. But I wouldn't believe that message." Smile and nod. There's nothing wrong with faking it every once in a while. As designer Jeffrey Zeldman writes in his book, Taking Your Talent to the Web, "You might hear [developers] talk about Perl, Java, ASP, PHP, SSI, XML, ColdFusion, and other technologies. Just smile and nod as if you get it." If all else fails, quote Star Trek.
|
|
