Work With Us

The Key To Writing Effective Developer Tasks

by Andy Carter
10 min read

Our Technical Team Lead, Andy, looks into what information is important when writing developer task descriptions for new features and bug fixes.

There’s an old sketch from ‘That Mitchell and Webb Look’. In it, a Bond-like villain is talking to his two henchmen. There is an individual that has become a problem to their criminal organisation. The bad guy wants him dealt with. One of the henchmen takes issue with the use of unclear instructions:

This is gonna be, ‘let's hope Professor Ritson meets with a little accident’, all over again. We spent nine months hoping that Professor Ritson would meet with an accident, before Leslie made it clear it was an accident we were supposed to make happen.

This can be a common issue in the world of development. Poorly worded tasks lead to misunderstandings, often resulting in delays in delivery.

In order for work to be carried out efficiently, and meet expectations, a well written task is essential.

The vast majority of tasks fall into two categories:

Let’s address these two task types and look at what is useful for a developer, and the wider team, in getting the work done.

NEW FEATURES AND CHANGE REQUESTS

WHAT AND WHY

Tasks should clearly and precisely describe what to achieve, and the reasonings behind it.

When a client requests new features, or changes, they often have an idea of how they want it to function. This is great, but knowing the reasons behind it may open up other ideas and solutions that better achieve the goal. As an agency, we are a team of creatives and problem solvers. Therefore, it is more valuable for us to understand what the client is trying to achieve and what is essential to the running of their business. Similarly, we want to know how important this is to the overall site, or if this feature is just for a niche group of people.

As a team we have many years of experience between us; we want to utilise this to offer our clients the best solution for them. We may be able to take an approach that is more cost effective, or improves on the user experience, than what the client originally had in mind.

IT’S ALL IN THE DETAIL

Going back to the Mitchell and Webb sketch, the villain makes a series of requests to take a detective, named Mr Harrison, ‘out of the picture’ and to ‘deal with the Harrison situation.’ One of the henchmen complains about the use of ambiguous terminology: 

Right. He has become a nuisance, but a nuisance we should murder, is that it? I mean my nephew's a nuisance, but you see what I mean?

Sometimes, the tasks given to a developer can feel a bit like this. 

Developers really appreciate clear and precise instructions. This is not to be awkward, but because vague details can easily be misinterpreted. A poorly worded task is likely to result in delays to the work as the developer will need to request more information.

Start all tasks with a concise summary of the request, then go into further detail. A concise summary will help the developer gain a quick understanding of the task, before they read through all the details.

When it comes to providing detailed information, assume that the developer knows less about what is wanted, rather than more. Provide context and details for things that may become relevant as the task is carried out. Tasks should provide as much detail as possible. 

Remember that the developer looking at the task may be new to the project, or have not worked on it for some time. Don’t assume that the developer will know or remember something critical to the site’s business logic.

BREAK DOWN THE TASK

With all the details outlined, it can be valuable to break down the task into a list of acceptance criteria. Listing what is expected in order to complete the task will help ensure that the developer doesn’t miss anything in the more descriptive details. It can act as a checklist for them to ensure each part is completed. It can also remove any ambiguity about what the client or project manager expects from the work.

There can also be value in getting the client to highlight priorities against the criteria. They may have talked a lot about some aspects of the request, but in reality they may just be nice to have.

This is not always necessary, but worth considering, especially for larger pieces of work.

PROVIDE MOCKUPS AND DIAGRAMS

If there’s a design for the new work, include it in the task. These really help everyone involved know what the finished feature should look like.

If designs aren’t available, then perhaps a mockup of what is required can be included. This could be a manipulated screenshot of an existing page.

Consider annotating any visuals. This can often clear up any confusion and help focus the developer on what is required. Add some arrows, outlines or annotations to the designs and mockups.

Sometimes a diagram can be beneficial. Perhaps a flowchart will clarify the required functionality. It’s important to remember that not everyone communicates in the same way. Some developers will appreciate a good visual more than just paragraphs of text.

If there’s copy that needs to be included in the work, make sure it is attached in a format that can easily be copy and pasted. If it’s just included within the visuals, someone will have to retype it which will be slower and more error-prone.

PROVIDE EXAMPLES

If the outcome of the task is to generate some sort of file, for example a CSV export, attach an example. Perhaps there’s some service integration required like connecting to a booking API or payment gateway; include links to the relevant documentation. These will all help ensure that the work meets expectations.

OUTLINE SPECIAL REQUIREMENTS

By default, we will build websites to work in all the modern browsers. However, some clients have specific requirements. For example, Internet Explorer is nearing its end of support from Microsoft and its user base is continually shrinking. However, some clients may need Explorer to still be supported, perhaps their staff use old computers. This sort of information needs to be communicated to the development team.

Perhaps the users of this new feature will predominantly use pay-as-you-go phones to access it. These users will usually pay more for the data they use than others and will often be limited by the amount they can afford to consume. Again, this sort of information needs passing on as particular care will be needed to ensure that the page size is kept to a minimum.

Any edge case or special requirements need to be clearly expressed. It is usually better for developers to have all the information upfront, rather than having to retrofit changes on work they’ve already completed.

PROVIDE CREDENTIALS

If the task needs to integrate with a third party service, then include the login details or ensure these are documented. If you don’t, delivery will be delayed as these will need to be requested.

BUDGET AND TIME CONSTRAINTS

Developers are creative people. They don’t like to be constrained in how they approach their work. However, in reality there are factors outside our control that dictate how they need to proceed with it. Budget and time constraints are usually crucial to the delivery of new work.

Sometimes, clients approach us with work that there is ‘no rush’ to complete, but in reality there is an undisclosed deadline. What may seem to the client to be a trivial piece of work, could be a lot more involved from a development perspective. It could therefore take longer to complete than anticipated by the client. There are many parts to the development process as discussed in our Debunking the ‘5 minute fix’ myth blog post.

It is useful to the developer that budgets or time frames are mentioned where available.

REPORTING BUGS

Bugs are an inevitable part of websites and applications. As developers, we aim to build flawless systems, but we’re only human and things get missed. They usually occur due to edge cases that were not contemplated during the testing and quality assurance checks. It’s therefore really important that when reporting bugs, as much detail can be provided as possible.

WHAT’S BROKEN?

When reporting a bug, provide a concise summary of the issue before going into further detail. As developers, we want to know what is broken and how it is normally expected to work. That last part is important, as it is not always obvious what the expected outcome is.

The more detail that can be provided about the bug the better. 

If possible, the task should include all the steps required to recreate the bug.

Include details of the browser and operating system where the bug occurred. What’s My Browser is a really useful website for determining this information; it will provide a link to all the useful information that might help a developer get to the bottom of the problem.

The old saying goes that pictures speak louder than words. Provide screenshots and/or screencasts of the bug. Annotated screenshots can add extra value.

The date and time a bug occurred can also be useful. It will help the developer track down any errors logged on the server. Some bugs are also the result of a particular action happening at a specific time.

HOW CRITICAL IS THE BUG?

Nobody likes bugs. It’s completely understandable that if a client discovers one, they will want it fixed. However, it is always worth knowing how critical the bug is to the client’s business. This will help us know how to prioritise work coming from the client and the value of the time spent fixing an issue.

For example, a broken image carousel on a product page may have a less negative impact on the business than a checkout page that is summing the basket incorrectly.

SUMMARY

For any task, the most important thing is to include a concise summary. For some simple tasks, this might be enough to get the work done. However, more often than not a task needs to provide more detail.

Depending on the task, the details we’ve described in this article can add huge value in getting work completed. 

To summarise, where appropriate the following should be included in task descriptions.

For new features and changes:

For bugs:

Had the villain in the sketch provided clearer task instructions, Professor Ritson would not have remained an issue for nine months. Similarly, there would have been no confusion over how the villain wanted the Mr Harrison problem being dealt with.

Communication is key to good development work. The information provided by the client and passed on by project managers is important. If the information is incomplete or ambiguous it can lead to delays, or an implementation that doesn’t meet the client’s expectations. This is not good for the client, and it’s not good for the development team as it can affect their morale.

Need help? Get in touch with our technical team now.

Written by Andy Carter
Technical Team Lead

With more than two decades’ coding experience under his belt, Senior Developer Andy continues to prove an integral part of the Evoluted development team. Having been with Evoluted since 2012, he has worked on countless projects for our clients. An analytical thinker, his background includes time spent working as a theoretical physicist; which involved research into Quantum Optics.

Related Blog Posts

Evoluted partners