Olga Isaeva

How to Prepare an Effective Brief for a Developer

One of the most common reasons for a development project to fail is poor documentation and communication. It's the client's responsibility to properly communicate specifications to the developer, or you could get a product that doesn't match your vision at all. To avoid this problem, you should sit down and document your ideas in a well-detailed brief. If you're unsure what to write, a project manager can help you but you still must communicate your vision. Here are some tips to prepare an effective brief for developers.

Write Down Your Initial Idea

This phase is generally just a brainstorming phase. Most development projects evolve over time, but you need to communicate your vision appropriately and build on a basic prototype after the initial phase. Brainstorming will ensure that you flesh out ideas and any function that you haven't thought of yet.

You won't give this documentation to the coders, so you can brainstorm your ideas either on paper or on whiteboard. Start with just the basics. Every application has a workflow, so you can draw basic wireframes for each application screen and then describe these screens in your own words.

Your initial ideas will be very high level, and you will need to clean up the writing before you present it to the developer. However, this will help you flesh out your ideas and cover all ideas before writing more official documentation.

Write Your Functionality Requirements

After you write your brainstorming content, it's time to clean up your writing and turn it into a list of functionality requirements. Functionality requirements tell the coder the way every element on your application should function.

For instance, suppose you have an ecommerce site and you want a custom shopping cart. Your functionality requirements should tell the coder what happens when a button is pressed, a dropdown is selected, or when the user adds and deletes products.

Functionality requirements should be very detailed, because coders use this document to program the backend exactly to your specifications. If they are unsure how a specific element should function, the development team should be able to reference back to this document to answer their questions.

Of course, you won't be able to cover every single question the coder has about your project, so you will still need to communicate ideas that aren't covered by the functional requirements, but it should be your goal to answer any questions before the project begins.

Determine Your Technical Requirements

While technical requirements aren't always a necessity, they will ensure that your software is developed on a platform that you can use. If you already have onsite developers, you need technical requirements to ensure that the onsite developers can maintain the software and fix bugs. If you don't have an onsite development team or someone who already handles existing software, this document is less essential.

Technical requirements include the platform and technical specifications that will run your software. These requirements usually aren't very long, but they can be detailed if you need your software to run on specific servers, network architecture, or mobile devices.

For instance, you might want developers to create a minimal viable product (MVP) that runs only on an Android device. You could later port the MVP to iOS should your product take off in the app store. This is a technical specification that the developers need to know to ensure that your software runs specifically on Android.

You can also specify specific web architecture. For instance, you might use Linux-based hosting and MySQL as a database. You can ask developers to build your web software and ensure that it runs on a Linux server with MySQL as the backend database platform.

If you have an internal network architecture, it might also help developers to understand the hardware the software will run on, but it isn't always necessary. Anything to communicate software details is better than no details at all.

Create Non-Functional Requirements

Whether you have a web, mobile or desktop application, you have non-functional requirements. Non-functional requirements include items such as performance, security, auditing specifications, and concurrent user load times. You might accidentally disregard these requirements, but when your software is too slow after 100 concurrent users, they become important.

It's assumed that your software should perform well, so you can specify the number of users that will work with the software and developers can test for this requirement. For security, you might have specific guidelines you must follow and auditing must be detailed. For instance, healthcare companies must follow strict HIPAA regulations or they can be heavily fined.

Developers work security into the code, especially with auditing requirements, so make sure you specify any of these procedures before your project begins.

Document Assumptions and Out-of-Scope Items

This part of the document is usually created by both you and the development team. Software projects are often at risk of going out-of-scope. This means that the client asks for changes in the middle of the project, and these changes can push back the deadline and increase costs.

Assumptions happen when you haven't specified an item and the developer comes across an issue that he can't code based on your documentation. Assumptions sometimes seem obvious to clients, but it's risky for a coder to assume certain functionality. A wrong assumption can lead to a product that does not function as required.

An assumption can be as small as a button placed on a form or as detailed as what happens when a user cancels and order. In many cases, there are standards to functionality but if you have any type of custom response, you must clearly define them in your documentation.

Communication is Key

After you create your document, you can work with a project manager or the development team directly to review it. Most development firms have a project manager for you to work with, and this person can ask questions and clear up any ambiguities with you.

Even with great documentation, communication is key for a successful project. Keep in touch with your project manager, and get back to the development team when they have questions.