Communicating clearly is an art to begin with, but throw some technically challenging problems into the mix, and it can become a nightmare. Here are some tips for avoiding miscommunication and creating harmony. I am going to start with some examples and then I will talk about them.
The basic formula (borrowed from Agile and modified) is this:
As a <user type> when I <explain action> I want <explain what you want to have happen as the result/need/outcome>. Also helpful here is: What is happening now is <say what is going on now that you do not want>.
Examples:
As a content creator, when I create a piece of content I want the path aliases for the pages to be automatically generated using the same patterns as are on our sister site. <URL to site>
As a manager of this project, when I visit the site, I would like to see the content that has already been created be retroactively assigned the patterns configured in the URL Aliases which should also (if not already created) match the patterns on our sister site, and for the existing menu items to also reflect those changes and point to the correct content. At the moment, the menu items go to a node URL like ‘/node/3’, and the aliases do not seem to get created in the correct language.
As an anonymous user on the site, when I visit the site, I want to be able to click on menu items in my language, and have them take me to the correct page alias in that language. At the moment the aliases getting created are not in the correct script, and some link to page-not-found error pages.
As your girlfriend, when I want to ask you something, I would like to not have to use Agile Methodology. (fair enough)
1. Avoid the prescribing how something should be executed and instead focus on the user and their experience.
One thing to notice that is important here, is the lack of technical information in the tickets. While some instances do require more technical instructions, most well written user stories do not require or prescribe any strictly technical information.
This is a good thing, because it enables you to communicate your needs effectively without having to understand the technical aspects of the issue. You might not know how it’s done, but the point is that you do not need to. Yay!
What I do need to understand is what you are wanting different users to experience. You have a good grasp of what you want the end result to be, and that is the exact information that is the most important to communicate.
The other thing you will notice is that these statements, while related, each communicate a specific experience/outcome from the perspective of different users. There are always a number of different people involved in making a website happen, and so it will be important to make sure that you describe what you are needing from each of their perspectives.
2. Clearly define expectations of what complete means (IE: acceptance criteria).
You will also note that because the stories are focused on the experiences and outcomes for specific users, the acceptance criteria or ‘when is this complete’ is, almost by definition, clearly defined.
The trick is making sure that you are including information for each user who will be interfacing with the end result you are wanting. As you can see from the examples above, the user can be someone on your own team.
3. Use URL references when important.
If there are specific pages that you are finding are not what you are expecting, it is always helpful to have a URL, but do not rely on the URL to tell the whole story. Having a clear ask, like the examples above, is also super important.
4. If something is not happening the way you are expecting, tell me what it is that you are expecting and relate it to what is happening now.
This is important because it enables me to quickly focus in on an aspect of something that is not working correctly, or something happening in the installation/configuration that needs to be fixed, and helps me differentiate between an error that might be happening in the setup and a need for additional training.
Employing these communication tricks might feel awkward at first, but they are worth practicing as they will lead your team into better and clearer communication.