Diviner Contributor Docs Describing Root Problems

Describing Root Problems
Phorge Contributor Documentation (Contributing in Detail)

Explains how to describe a root problem effectively.

Overview

We receive many feature requests with poor problem descriptions. You may have filed such a request if you've been sent here. This document explains what we want, and how to give us the information to help you.

We will never implement a feature request without first understanding the root problem.

Good problem descriptions let us answer your questions quickly and correctly, and suggest workarounds or alternate ways to accomplish what you want.

Poor problem descriptions require us to ask multiple clarifying questions and do not give us enough information to suggest alternate solutions or workarounds. We need to keep going back and forth to understand the problem you're really facing, which means it will take a long time to get the answer you want.

What We Want

We want a description of your overarching goal. The problem you started trying to solve first, long before you decided what feature you needed.

This doesn't need to be very detailed, we just need to know what you are ultimately hoping to accomplish.

Problem descriptions should include context and explain why you're encountering a problem and why it's important for you to resolve it.

Here are some examples of good ways to start a problem description:

My company does contracting work for government agencies. Because of the nature of our customers, deadlines are critical and it's very important for us to keep track of where we are on a timeline. We're using Maniphest to track tasks...

I have poor eyesight, and use a screenreader to help me use software like Phorge in my job as a developer. I'm having difficulty...

We work on a large server program which has very long compile times. Switching branches is a huge pain (you have to rebuild the binary after every switch, which takes about 8 minutes), but we've recently begun using git worktree to help, which has made life a lot better. However, ...

I triage manual test failures from our offshore QA team. Here's how our workflow works...

All of these descriptions are helpful: the provide context about what goals you're trying to accomplish and why.

Here are some examples of ways to start a problem description that probably are not very good:

Add custom keyboard shortcuts.

I have a problem: there is no way to download .tar archives of repositories.

I want an RSS feed of my tokens. My root problem is that I do not have an RSS feed of my tokens.

There is no way to see other users' email addresses. That is a problem.

I've used some other software that has a cool feature. Phorge should have that feature too.

These problem descriptions are not helpful. They do not describe goals or provide context.

"5 Whys" Technique

If you're having trouble understanding what we're asking for, one technique which may help is ask yourself "Why?" repeatedly. Each answer will usually get you closer to describing the root problem.

For example:

I want custom keyboard shortcuts.

This is a very poor feature request which does not describe the root problem. It limits us to only one possible solution. Try asking "Why?" to get closer to the root problem.

Why? I want to add a shortcut to create a new task.

This is still very poor, but we can now think about solutions involving making this whole flow easier, or adding a shortcut for exactly this to the upstream, which might be a lot easier than adding custom keyboard shortcuts.

It's common to stop here and report this as your root problem. This is not a root problem. This problem is only slightly more general than the one we started with. Let's ask "Why?" again to get closer to the root problem.

Why? I create a lot of very similar tasks every day.

This is still quite poor, but we can now think about solutions like a bulk task creation flow, or maybe point you at task creation templating or prefilling or the Conduit API or email integration or Doorkeeper.

Why? The other developers email me issues and I copy/paste them into Maniphest.

This is getting closer, but still doesn't tell us what your goal is.

Why? We set up email integration before, but each task needs to have specific projects so that didn't work and now I'm stuck doing the entry by hand.

This is in the realm of reasonable, and likely easy to solve with custom inbound addresses and Herald rules, or with a small extension to Herald. We might try to improve the documentation to make the feature easier to discover or understand.

You could (and should) go even further than this and explain why tasks need to be tagged with specific projects. It's very easy to provide more context and can only improve the speed and quality of our response.

Note that this solution (Herald rules on inbound email) has nothing to do with the narrow feature request (keyboard shortcuts) that you otherwise arrived at, but there's no possible way we can suggest a solution involving email integration or Herald if your report doesn't even mention that part of the context.

Additional Resources

Poor problem descriptions are a common issue in software development and extensively documented elsewhere. Here are some additional resources describing how to describe problems and ask questions effectively:

How To Ask Questions The Smart Way, by Eric S. Raymond
XY Problem
5 Whys Technique

Asking good questions and describing problems clearly is an important, fundamental communication skill that software professionals should cultivate.

Next Steps

Continue by:

returning to Contributing Feature Requests.

Defined: src/docs/contributor/describing_problems.diviner:1