Issue description and communication
Daily hassles we all eventually find ourselves into, when documenting an idea, be it a bug or a feature request, and some simple guidelines to follow in order to make our lives so much easier (and fun).
“Where to start” should be a section on its own as part of the ‘specs’ of any new issue or feature request, specially when assigned to junior developers and new personnel!
Issues come with a title, a (hopefully short) description, and relevant technical specs. They should also come with ‘next steps’ or ‘where to start from’.
While the issue at hand may be obvious to the submitter, that’s not necessarily the case for anyone else reading it! Not everyone knows this part of the web application, not everyone even fully understands the concept of billing, for example (if this were an issue about a new billing feature). And even if we do, we don’t necessarily know the exact business needs about how and when we want to bill clients (and honestly it is probably not our decision to make all by ourselves!).
We may even get what is currently implemented, how that works and have a fairly good idea of what we aim to achieve with this issue, but yet not be completely sure how we can code this from a technical perspective. We are not magicians after all — we need to think about it!
If someone has already thought of this, it would be great if they shared their insights! If not, then maybe this issue is not ready to be assigned for development but instead it needs some brainstorming about how to approach it.
Takeaways:
- Read, read, and read again.
- Break down your thoughts
- Ask meaningful questions (and briefly explain how you came up with this conclusion)
- Look at the code! (all the answers may be there)
- Be aware of assumptions you may be making along the way
Introducing a new section in issue templates!
Just reading the issue’s title may mean a lot to a project maintainer. A long term contributor or even product owner, can think of 10 different sub cases, prerequisites or limitations in a glimpse of a second when reading just a few words.
And then the developer, to whom the issue is assigned, tries to decrypt all that hidden information behind months or years of research and design, and unravel the mystery behind why this is even needed and not already satisfied by the current implementation. And of course.. where the hell to start from!
Sometimes we are bad with specs.
Sometimes we are worse with communicating what’s on our minds. And no one really taught us how to ask the right questions.
Or how to break down our thoughts, so that instead of this huge mess we end up with meaningful, and short, questions or points.
How to understand a concept 101
- Read the issue again. And again. And at least 3 times, but also up to 5 times before coming up with your final questions
- Read those lines in a way you are really taking in the words and their meaning — don’t just roll your eyes on top of the words!
Quick search of unknown words — you may stumble upon a concept you don’t entirely grasp or maybe you know a word but the context in which the word is used is confusing. Go ahead and do a quick search to find the meaning of the word, even in your native language if that helps, or scan the results for references in real-life scenarios. You may just need to read up on the definition of a concept (and perhaps only to understand it is something you know very well after all, just wasn’t familiar with the term! Look at that, you learn something new every day!
Pro tip: Copy-paste the word/phrase to avoid typos!
How long should this take?
This should take less than 1 minute to do so that you
- don’t lose your focus from the issue description you were reading, and
- don’t lose the connection between that word/concept and the text you were reading
If it takes you more than ~1 minute, you may need to proceed to the next step and ask a colleague about this.
Talk to your team — break down your thoughts
Ask for clarifications in a meaningful way. If I wrote an issue description, I most likely think it is well put and self-explanatory, and adequately defines the problem, even the direction of the solution we want to take. I may be wrong. You need to show me how and where.
Writing down what you want to ask is really powerful here.
By writing your thoughts down, you deconstruct your one big black-box thought into smaller concepts/questions/sub-cases. And guess what? You may actually be able to tackle some of those written down smaller questions on your own! Isn’t that amazing?
For example — and that’s not the best documented issue ever, but it is not unlikely you find yourself facing this as an issue documented real quick during QA’ing a completely different feature, or during a customer call about something else (when something catches our eye, it is good to document it — then it is also good to go back and work on it!)
Examples are completely imaginary, yet inspired by real life :)
Imagine the following issue description:
“The user having navigated from the login screen to the order’s page, is now faced with this huge table showing all past orders that endlessly scrolls down”
Well that sucks, but I have no clue what to do with it!
Now, breaking down an issue could mean that from the above example we come up with the following questions:
- Is this page supposed to show all customer’s orders or just the most recent ones? (And what does recent mean technically speaking?)
- Could we perhaps limit the page with the latest 3 or 5 orders and have a link for showing more?
- Do we need to show all details of an order, or can we just show 1 line with a couple of useful information? I am thinking that it could show the order identification number, which can be useful to uniquely identify the order if the customer contacts us, but also something more meaningful for customers themselves like date, total amount, number of items ordered. These could be collapsible too, right?
- When a user logs in, should the user be redirected in this page or perhaps it could help increase our revenue if we redirect the user to a new page where the user can make a new purchase? Or even better where we suggest items to be purchased?
Yeah what’s described in the issue is a problem — or actually multiple problems, not all of which we can decide on ourselves or even solve with this issue. So we need to pinpoint which issue we need to focus on.
Maybe this was considered to be a rather not too big issue about improving the user’s experience after logging in. Does that mean a full redesign of the orders page? Probably not. Or perhaps I call this a small issue, but it’s rather a big-ish feature.
Instead of merely asking “what’s the goal of this issue?” try to come up with answers to that question on your own — and write the answers down in the issue comments!
When I read “What’s the goal of this issue?” the response that automatically comes to mind is “exactly what is described in the issue description, have you read it?”
But that’s not what’s going on here. What’s going on is that you read the description, 5 times even, and you have also thought of 5 different ways this can improve. Maybe none of which you can develop within the time estimated for this particular issue.
So you need to phrase that. For example
“I think it would improve our users experience if we redesigned the orders page. I even have some ideas about how to do that: (bullet points with ideas). How do you feel about that?”
I probably feel like ‘absolutely not’ because this wasn’t supposed to be a new feature that needs mockups and more people getting involved with that and 1 month later to still be reviewing the new UI and deciding if we improved UX or not. Don’t take this the wrong way though, your ideas may be great. Great to be documented in a new issue, regarding the redesign of orders page, and properly scheduled in a different sprint.
Now back to the problem itself. You should provide at least a plan B, if your first suggestion doesn’t work within the constraints of your team and project. For example:
“A quick workaround would be to redirect user to another page instead, eg products page. That would improve the login experience. But we still need to think about the orders page because it’s problematic when users find themselves there. Should I open a new issue with the above-mentioned ideas? Is this redesign something we are interested in?”
Maybe we are interested in it, but not able to pay for it. Again, don’t take this the wrong way, we need to make tough decisions.
Now that our plan is more to the point of the issue at hand, and it is also fast (assuming there is a products page, of course!) we can get productive!
You should always pinpoint the relevant code. Look at the code (and this shouldn’t take you more than ~5–10 minutes) to determine which orders are supposed to be loaded in this page — there is a variable somewhere that somehow gets those order records. Maybe there is a bug in that code, and while it is meant to only bring the most recent order, it queries for all of them.
In your comment, provide a link to the specific line of code where the orders are being fetched, and briefly mention why you think there is a bug.
For example:
This line (with link) is loading all orders of a specific customer, however it depends on the variable xyz above which is supposed to limit the results to only the last 3 purchases. Still, locally I see that all 10 purchases being loaded for my test user X (if defining the user matters, please do so! Is the user a simple user or an admin? Is this a dev environment that everyone can use? If so, let people know the user so that they can try this on their own locally). Maybe there is in fact a bug, and solving this bug, would solve this issue.
Try to communicate as much of your thoughts and assumptions as possible
Opportunities behind every obstacle
Take this opportunity to learn how you should improve the description of the issues you are adding!
And also take this as an opportunity to learn
- how to get things done, and
- how to break down big ideas into tackable, doable, feasible, tangible sub-tasks
Because let’s face it, as you grow, eventually you are going to find yourself in a position where you need to take this huge idea and make it into something very very specific which you can write code for in order to implement it.
Breaking down into sub-tasks is a big skill in project management, but it is not useful only to project managers!
🎉 Happy coding 🎉