Writing Technical Requirements: How to Articulate Design Ideas to Developers

June 24, 2015

It's difficult to relate to developers, but imagine yourself in a position where you hear ideas every day and need to translate these ideas into code. Superficially, it sounds easy, but it's actually one of the most difficult parts of the development life cycle.

This guide is for site owners or creative innovators who need to write business requirements for developers. The right business requirements ensure project completion within a given deadline and increase the chance of project success.

Step One: Draw Your Screens

Whether you borrow inspiration from other sites or have specific screens in mind, the first step is to draw your screens. You can draw them on a tablet or on paper. Your developer must code for each screen, so you should draw each screen individually on a separate piece of paper or document page.

These images are called wireframes. Wireframes give developers a general idea of how you want your pages to look. The more direction you give your developers about the design, the easier it is for the developer to address each requirement and the better likelihood that your design ideas will be properly addressed.

For instance, suppose you have an ecommerce store idea. You want to display a small image to users and have them click the image to see more product details. Draw your main page layout with the small image, and then draw the screen that displays product details. You can use placeholders or just scribble "Image" on your design. You don't need to be an artist, but each screen should have enough details where the coder and designer understand your idea.

If you have ideas for logos, navigation or any other page elements, draw them on your screens. Your developer can help you with design and give you ideas, but you should always give any instructions when you have specific requirements for any HTML elements.

Step Two: Describe Your Screens

To you, functionality and user experience might seem obvious. However, it's not always obvious to the developer. For instance, you probably think a login screen has standard functionality without the need to explain details to the developer. The user just enters a user name and password, right?

In fact, there are several questions that a developer could present for a login screen. These requirements must be fleshed out by the site owner. Will the user enter an email address as the user name? How many times can the user enter a wrong password before getting locked out for security? How do you handle password reminders? These are just a few questions that your developer will ask if you aren't specific in your requirements.

This step is the most important for technical requirements.  You must be detailed and specific enough for a developer, project manager, and business managers to understand. These requirements are the catalyst for your design and prototype. Here are some tips when writing your requirements.

Define One Requirement at a Time

One reason you want to draw your screens first is to separate your ideas into components. These components need detailed descriptions, but you want to create a description one at a time. Using the login screen example, you might have dozens of requirements for a login screen. Number each one of them and describe them in detail. For instance:

  1. User enters user name, which must be the user's email address.
  2. User enters password, which must be at least 6 characters.
  3. User clicks the "Login" button.
  4. Successful login redirects to user's profile page.
  5. Unsuccessful login keeps user on login page and displays an error.

Don't Offer Compromises

Be specific, and don't use any clauses that give the developer an option to leave out the requirement. For instance, don't use terms such as "if necessary" or "possibly." If you want a user to log in and redirect to a profile page, say it's what you want. Don't give the developer options on technicalities that you truly want developed. Developers will avoid adding requirements that could upset a customer, so ensure that you specify exactly what you want with your new app.

Be Succinct But Direct

Avoid long sentences that ramble at the developer. The developer uses your documentation to find answers to common technical requirement questions. They need to know exactly what needs to be done without misunderstanding the requirements. The more you ramble, the greater the chance a developer will misunderstand a technical detail.

Avoid Duplication

Don't duplicate requirements in several sections. This is also a reason to draw your screens first. When you duplicate requirements in several areas, you run the risk of creating contradictory or convoluted statements.

Use Positive Statements

There are dozens of possibilities for user input and response. Your job as a site creator is to identify what the system should do, not what it shouldn't do. Write your content with positive statements such as "The system redirects logged in users to the profile page." Don't write something such as "The system should not redirect to the subscription page." When you use positive statements, the developer does not need to assume other possibilities. You also make your requirements shorter and more succinct.

Step Three: Proof Your Requirements

Grammar and sentence structure might seem insignificant, but clear instructions are important. You could accidentally type the wrong word and change the entire outcome of your project. You don't just want to proof for grammar and spelling errors. You want to read for logical flow and clarity.

To ensure clarity, proofread your documentation but also have someone else help you with sentence structure. Ask someone else to read the documentation and explain how he understands the functionality and system requirements. What might seem clear to you might not be to someone else. It's difficult to express design ideas on paper, so have a third-party help to identify any possible misunderstandings.

Step Four: Deliver Your Requirements and Lock Down Scope

The final step is to deliver your requirements to your developer. The developer needs time to read through each requirement. You will probably meet with a lead designer who will then relay the information to the developers on a team. Some development shops use project managers for communication between clients and developers.

After requirements are reviewed, both you and the developer come to an agreement about scope. The Scope of Work (SOW) document identifies what's expected from the developer and the customer. It lets you know what you can expect from your designs and requirements. The SOW is used to direct the development process, so the project does not steer off into a different direction. Even the smallest change of scope can greatly increase development time. The developer will hold you to the SOW, so ensure that you read the entire document before you sign it.

After all steps are complete, you wait for your project. Developers usually give you status and a demo of the product as it's designed and coded. It could take days, weeks and even months before you see a demo. Be patient. A great project takes attention to detail, and it's this attention that makes a quality product in the end.

by on June 24, 2015

e-dimensionz Inc is a web development company based in Kitchener-Waterloo
specializing in custom websites, CMS frameworks, mobile applications, and Open Source technology
e-dimensionz Inc, 888-635-9679, info [@] e-dimensionz.com