sdellis / sdellis.github.io Goto Github PK

Slides

Ok, PET PEEVE that negatively affects my (and others) work experience: GitHub Issues!

I get it. Everyone is busy. When we identify an issue, we often want to create an issue as quickly as possible so we don't forget to address it before we encounter the next distraction.

However, when you enter an issue that:

1. Provides a solution without stating the problem.
2. Has no contextual information.
3. Has no examples, links, or screenshots of the problem.

Congratulations, you have just offset the work to whoever has to work on the issue. Sometimes parsing the issue can be more frustrating and time consuming than the task itself. Writing good GitHub issues is HARD. But it's HARDER for someone to interpret a poorly written issue.

Separate the problem from possible solutions.

I do a lot of UX work. When you are designing something you want to know what your users' goals are. A problem statement is born from a user that cannot achieve their goal.

Here's an example of how a solution can sneak into a problem statement:

As a consumer of drag and drop, I want to have confidence that the dragged icon will appear in my viewer.

Drag and Drop is a solution to opening a file. The problem could happen in any context of trying to open a file. Thinking about problems that could occur when trying to open a file by any method could lead to better and more robust solutions.

Improve your UI design solutions by considering many ideas before settling on any one of them. A solid ideation methodology broadens your idea-generation capacity.

Nielson Norman Group
Citation: https://www.nngroup.com/articles/ux-ideation/

Provide Context

You may retort, "My team has been working on this project for a month. I can provide the minimal amount of information because they have all the contextual information they need." Context information means answering the: Who? When? What? and Why?

The problem with that is sometimes issues don't get resolved right away and they get pushed to the next sprint. By the next sprint, much time may have passed. By the next sprint the team may be different. By the next sprint, no one may have any idea what the issue even means.

Here's an example issue I was assigned recently:

File Manager: Make it easier to find where to download a file's full resolution image from

This was a new use case. The File Manager UI is intended to allow users to:

1. upload images
2. relabel or reorder these images

Why would someone who likely uploaded the hi-res files need to then download them? I have no context in which to interpret this, so I cannot come up with the best solution.

After several back-and-forths, it turns out that our "Photoduplication staff" need to download hi-res images for to fulfill patron and commercial requests. Replacing, deleting, or downloading images is only accessible via the Filemanager, however there is nothing stopping our "Photoduplication staff" from accidentally relabeling or reordering the objects. This whole "proposed workaround solution" to a completely new use case took a lot of energy and time, without actually stating the real problem.

I am a UX proponent and I happened to get this issue. Others may not have questioned this request and simply changed the wording on the button. This is how bad software is written.

Offer Examples

Sometimes people will put in an issue like this:

"Breadcrumbs are broken."

If the breadcrumbs are not broken on every page, you are expecting someone to track down the page with broken breadcrumbs. Even if this is a display issue, another user may be using a different browser or device that does not have an issue. A screenshot goes a long way in these scenarios. Finally, perhaps breadcrumbs display fine, but the hierarchy or the data is wrong.

So for the sake of a happy developer experience and better software please, please, please take some time to:

1. State the problem before providing a solution
2. Provide context: Who? When? What? Why?
3. Provide examples in the form of links, screenshots, and GIFs if interactions are involved