10+ tips on how to effectively describe tasks for your dev team (2023)

(Video) Top 10 PRODUCTIVITY Tips & Tricks for iPad

by RubyOnRails Developers @ Selleo

The implementation of every new feature or change (hopefully) begins with reading some sort of specification, expectations description, investigating mockups, research etc. If the quality of this step is poor, the tasks delivered might not fulfill the product owner’s expectations and/or may be delivered later rather than sooner. On the other hand, if appropriate measures are taken to provide high quality task descriptions, such tasks will most likely be handled efficiently, accurately and on time. It is crucial for a coder to understand both the problem/domain and the product owner’s expectations to effectively proceed with development.

How much attention a developer pays to investigating those expectations and how much time they spends on research is up to each individual, however, as a Product Owners, you can have a huge impact on the quality of requirements specification and how the latter are managed. The list below may not be complete or it may not fully fit each and every development environment, yet it can act as a strong starting point for building your own set of practices.

New features are what every product owner loves the most. How to manage the requirements for those to be delivered effectively? The following tips should help:

1. Keep all the updated requirements in one place. There is hardly anything more frustrating than having to look for current requirements in tens of comments under the actual description or having to decide which commenter is actually authorized to change the requirements. The goal here is to keep all the up-to-date requirements and details in the main/primary description of a task. Even though the information in comments may affect initial criteria, just update this primary description accordingly.
2. Consider creating an acceptance criteria list. Descriptive requirements are very helpful when it comes to understanding the context of a problem, yet finally it is good to precisely specify what is expected. Thus the developer will not have to look for the actual requirements in a long, descriptive text but he will be able to easily get to the essence. One might find that sometimes — when acceptance criteria are well defined — there is little or no need for any additional information. Example:
   a) User navigates to “/accounts” and clicks on red download CSV button
   b) Popup appears with two buttons: “This year” and “Last year”
   c) If user clicked on “Last year” download is initiated
   d) CSV downloaded includes following columns…
3. Provide mockups. A textual requirements description is essential in most cases, but an image is often worth more than a thousand words. Even a simple mockup can limit misunderstandings by a great factor. There are many apps out there that might be helpful here, like Balsamiq, InVision or Mockingbird, but manipulating screenshots of an existing app also works.
4. Provide examples, credentials, etc. If the expectation is to process or generate some file — attach an example of such a file. If the goal is to integrate what is being developed with some service, ensure your devs have access to this service and its documentation. This list could go on and on — the bottom line is — if there is something that our developer might make use of, try to foresee it and provide them with (access to) it.
5. Annotate. The mockup provided can sometimes be confusing for developers. Especially if it contains much more content than the scope of the task described. Drop a couple of arrows, outlines and annotations here and there to emphasize what are the important parts of the mockup from the task requirements perspective.
6. Use charts and diagrams. While it is not always necessary, sometimes it might be beneficial to prepare a flowchart, a block diagram or some other kind of concept visualization that will render it easy for the developer to comprehend the task and its scope.
7. Spoil your developers with details. It is always safer to assume less rather than more domain knowledge in the dev team. Therefore following the KISS principle and augmenting each description or acceptance criteria list with contextual/domain knowledge and details that might become relevant is highly recommended.
8. Describe edge cases and provide constraints. Hardly any developer likes constraints, but if there are some, let them be communicated early. Do we need to support some specific browsers? Does this script need to run below a specific amount of time? Is it crucial for this endpoint to respond in no more than n milliseconds? If there are some such concerns, make sure they are included in your descriptions. Also describing any edge cases might be beneficial. Maybe we have some query limit on a given service? If you have such knowledge it is always beneficial for your devs to know about it upfront.
9. Provide a copy. If there is a long message to be displayed, just provide a copy for it somewhere in the description. Do not place it on mockups as it is always slower and more error-prone to re-type it than to copy-paste it.

It might have happened a couple of times that you have received a response to a bug report stating “cannot reproduce”. Hence it is also important how you describe bugfix requests.

1. Describe steps to reproduce an issue including as many details as possible.
2. Provide access to the affected account and services if possible. It might be hard to reproduce the exact environment on a local machine.
3. Provide environment information, i.e., browser version, operating system version etc. Sometimes a list of installed browser plugins and extensions might be helpful as well.
4. Provide a link to an exception and/or a stack trace, as investigating those is usually the first step to take in resolving the problem.
5. Provide access to logs, as they can be helpful in reproducing the steps that caused the problem in the first place.
6. Provide access to the affected server or database dump. If it is possible and when it does not violate security policies, it is usually helpful for the developer to access the original data that might have played a role in the problem.
7. Make a screencast. It is not always necessary, but many times a short screencast (or at least a screenshot) says more than a thousand words. While working on MacOS you can use QuickTime Player for the purpose but there are plenty of tools available for other operating systems as well.
8. Provide contact information of the person that reported the bug. This will not always be possible, but in some cases it might be advantageous and most effective if a developer can have a chat with a person that actually experienced the bug, especially if the steps to reproduce a problem are not deterministic.

Communicating requirements effectively plays a big role in the development process. Doing it wrong may cause delays in requirements delivery or lead to the implementation of features that diverge from product owner’s expectations, but it can also result in building up frustration and lowering the team morale. The list above might become helpful in mitigating such effects significantly. Following the checklist can be helpful when you add new items to the backlog — just go through all the points below and determine if each is important, not important or irrelevant in your specific context.

Features and changes

• Requirements are updated in one place
• An acceptance criteria list is available
• (Annotated) mockups are provided
• Relevant examples are in place (i.e. files, calculations)
• Access to necessary services is ensured
• Necessary diagrams and charts have been delivered
• The context of tasks is described well enough / in sufficient detail
• Important constraints and edge cases are added
• Copy text is provided

Bugs

• Steps to reproduce the bug have been provided
• If possible, access to the affected account has been ensured
• Information about the environment in which the problem occurred is available
• Screencast(s) visualizing the problem are in place
• An exception report and/or stack trace is provided
• Access to server and/or database is provided
• Access to logs and/or logging service is provided
• Contact information to the bug reporter is available

Most of the time applying just a few of the tips above will make a huge difference and picking the right set depends on a given feature or situation. On the other hand, sometimes just one sentence might be good enough to properly handle a task — as usual, it is a matter of finding a sweet spot that balances effort/costs and benefits. This being said, I hope this article will help you make the development process smoother and your dev team — both more productive and happier.