Writing Issues: WHAT, WHY and HOW

Open Approach asks us to write clear, concise and informative issues.

One pattern that solves this problem is to follow the practice of having WHAT, WHY and HOW for every issue that you right.

THE WHAT

The What part of an issue is what describes the issue to anyone reading it – be it your teammate, your manager or you in the future.

This is the part that makes it clear what we are trying to achieve with that issue –

• Is it a bug we are trying to fix? If so, what is the bug? What are the steps to replicate the bug?
• Is it a new feature we are onboarding? If so, what is the feature about? What will the feature be? How will the users make use of the feature?
• Is it a discussion/potential change? If so, what parts of the application are we trying to change? Is it a backend/frontend change? What benefits would making this change have?

When we talk about describing the issue to a reader, what we mean is we describe what is it that we’re trying to achieve by working on the issue and what would the result be.

It could be something as simple as “We need a button on the navbar that would open up a modal with a signup form for users to sign up with”. This “what” clearly describes what the end goal of the issue is (a signup form for the users) and what do we need to do with the application to achieve this (give a button that opens up a modal).

The more concise the “what” part of the issue description – the better. Beating around the bush would just result in the reader being confused about the requirement.

THE WHY

The second part is the Why. The why part answers the following question - Why is the change that is described in the “what” being made?

A great “Why” should ideally make it clear to the reader the benefits as well as the drawbacks, if any, of the task being done (and how the benefits are overpowering the drawbacks).

In most cases, the why should be talked about from the point of view of the end-user or the client. If it is a client requirement, we need to explain why the client has come up with the requirement and what he seems to achieve with this particular feature. If not a client requirement, we can discuss why the task is helpful or beneficial for the end user and how the change will bring about a positive change in the application – be it a UI/UX change, a new feature of fixing of a bug.

Sometimes, there will be issues that need to be worked upon on the backend or devops part of the application – even in these cases a “Why” describing the issue is equally important even though the changes do not directly affect the client/end user. The why in this case can explain to your teammates what benefits would the issue bring when completed – maybe faster load times, more stability with deployment or just about anything.

There will be times when you will find yourself writing the same “why” again and again for multiple issues, what can be done then is that the why can be written down as a GitLab wiki that can be linked to from the various issues it is connected to or we could have a parent issue that is linked to all the child issues and the parent issue has the WHY for all the child issues as well.

THE HOW

The third and final part of the trilogy is the “How” - This is the part that was mainly discussed with the mini-example that we saw in the “An overview of open approach” section.

The how part of an issue is mainly focused on the approach that you are taking to solve the particular issue you’re working on. This is also the part that you’ll be iterating the most on. The what and the why are more of one time jobs, at max two. The how part however would need constant updating. In fact, every time you’ll change your approach to solving the problem, you’ll have to update the how.

I like to think of the “how” to have a lifecycle consisting of three separate parts – the initial How, the How under work and the final How.

The initial how is the one that you write during the time of issue creation (or when you start working on the issue) - this would be the one that you start off with, your initial approach at solving the issue.

Then, when you are working on the issue, you keep on updating your progress in the form of commits and sometimes also in the form of comments on the issue. If you find yourself changing the approach that you took with the issue, you also need to edit the ‘How’ that you had written as the initial how. This is what we mean by keeping the “how” updated.

The final how would then be the how that exists during the time of closing the issue. This how should reflect the approach that was finally agreed upon (if after a discussion) and then used to complete the issue. The final how would help anyone reading the issue in the future to understand how the issue was solved while the comments on the issue would indicate on how we reached that solution.

The contents of the “How” would include anything that was used to solve the issue – it may be a stackoverflow answer, a blog post, a youtube video or any other reference that you found on the internet. It might also be possible that you came up with a solution on your own, in that case, please include the “How” you came up with the solution as well.

The “How” aims to act as documentation for the solution of a problem so that any future reader spends lesser time and has more insight on how the engineer that solved the issue solved it.

Example

A simple example issue with a what, why and how can be found here – Signup form creation example.