Advice On Writing Website Amends And Issues

At some point when building a website you're most likely going to have amends or issues to fix. As a developer it's important that the way the amend or issue is communicated as best possible. Here's some tips and things I find help me to make amends and fix issues efficiently.

When writing an amend or issue for a developer try to think about approaching it with fresh eyes. For example, you might know where the issue is as it's in front of you. But if someone else comes to it, is it obvious where it is? or how to reproduce what's happening? If not, then add a link, a description of where it is, a screenshot or how to reproduce.

The main thing that helps me and the reason for this post and my biggest tip is to make things actionable. If we look at the following examples;

• It doesn't work.
• This is wrong.
• X doesn't do Y.

None of these are actionable. I'm left confused, searching around to try and figure out what actually needs to be done.

So;

• Rather than saying something doesn't work, say what will make it work.
• Rather than saying it's wrong, say what will make it right.
• Rather than X doesn't do Y, say what X should do.

The idea here is to make the amend or issue as easy to complete as possible. I'm a lazy developer and as such I don't want to have to try and work out what it is that actually needs to be done, this takes time and is more likely to lead to a mistake.

Having smaller actionable tasks I find is super productive.

As a bonus ProTip when going over a GitHub / BitBucket list of issues, you can close an issue using the commit message https://help.github.com/articles/closing-issues-via-commit-messages/.