src/docs/contributor/describing_problems.diviner

   1 @title Describing Root Problems
   2 @group detail
   3
   4 Explains how to describe a root problem effectively.
   5
   6 Overview
   7 ========
   8
   9 We receive many feature requests with poor problem descriptions. You may have
  10 filed such a request if you've been sent here. This document explains what we
  11 want, and how to give us the information to help you.
  12
  13 We will **never** implement a feature request without first understanding the
  14 root problem.
  15
  16 Good problem descriptions let us answer your questions quickly and correctly,
  17 and suggest workarounds or alternate ways to accomplish what you want.
  18
  19 Poor problem descriptions require us to ask multiple clarifying questions and
  20 do not give us enough information to suggest alternate solutions or
  21 workarounds. We need to keep going back and forth to understand the problem
  22 you're really facing, which means it will take a long time to get the answer
  23 you want.
  24
  25
  26 What We Want
  27 ============
  28
  29 We want a description of your overarching goal. The problem you started trying
  30 to solve first, long before you decided what feature you needed.
  31
  32 This doesn't need to be very detailed, we just need to know what you are
  33 ultimately hoping to accomplish.
  34
  35 Problem descriptions should include context and explain why you're encountering
  36 a problem and why it's important for you to resolve it.
  37
  38 Here are some examples of good ways to start a problem description:
  39
  40 > My company does contracting work for government agencies. Because of the
  41 > nature of our customers, deadlines are critical and it's very important
  42 > for us to keep track of where we are on a timeline. We're using Maniphest
  43 > to track tasks...
  44
  45 > I have poor eyesight, and use a screenreader to help me use software like
  46 > Phabricator in my job as a developer. I'm having difficulty...
  47
  48 > We work on a large server program which has very long compile times.
  49 > Switching branches is a huge pain (you have to rebuild the binary after
  50 > every switch, which takes about 8 minutes), but we've recently begun using
  51 > `git worktree` to help, which has made life a lot better. However, ...
  52
  53 > I triage manual test failures from our offshore QA team. Here's how our
  54 > workflow works...
  55
  56 All of these descriptions are helpful: the provide context about what goals
  57 you're trying to accomplish and why.
  58
  59 Here are some examples of ways to start a problem description that probably
  60 are not very good:
  61
  62 > {icon times color=red} Add custom keyboard shortcuts.
  63
  64 > {icon times color=red} I have a problem: there is no way to download
  65 > .tar archives of repositories.
  66
  67 > {icon times color=red} I want an RSS feed of my tokens. My root problem is
  68 > that I do not have an RSS feed of my tokens.
  69
  70 > {icon times color=red} There is no way to see other users' email addresses.
  71 > That is a problem.
  72
  73 > {icon times color=red} I've used some other software that has a cool
  74 > feature. Phabricator should have that feature too.
  75
  76 These problem descriptions are not helpful. They do not describe goals or
  77 provide context.
  78
  79
  80 "5 Whys" Technique
  81 ================
  82
  83 If you're having trouble understanding what we're asking for, one technique
  84 which may help is ask yourself "Why?" repeatedly. Each answer will usually
  85 get you closer to describing the root problem.
  86
  87 For example:
  88
  89 > I want custom keyboard shortcuts.
  90
  91 This is a very poor feature request which does not describe the root problem.
  92 It limits us to only one possible solution. Try asking "Why?" to get closer
  93 to the root problem.
  94
  95 > **Why?**
  96 > I want to add a shortcut to create a new task.
  97
  98 This is still very poor, but we can now think about solutions involving making
  99 this whole flow easier, or adding a shortcut for exactly this to the upstream,
 100 which might be a lot easier than adding custom keyboard shortcuts.
 101
 102 It's common to stop here and report this as your root problem. This is **not**
 103 a root problem. This problem is only //slightly// more general than the one
 104 we started with. Let's ask "Why?" again to get closer to the root problem.
 105
 106 > **Why?**
 107 > I create a lot of very similar tasks every day.
 108
 109 This is still quite poor, but we can now think about solutions like a bulk task
 110 creation flow, or maybe point you at task creation templating or prefilling or
 111 the Conduit API or email integration or Doorkeeper.
 112
 113 > **Why?**
 114 > The other developers email me issues and I copy/paste them into Maniphest.
 115
 116 This is getting closer, but still doesn't tell us what your goal is.
 117
 118 > **Why?**
 119 > We set up email integration before, but each task needs to have specific
 120 > projects so that didn't work and now I'm stuck doing the entry by hand.
 121
 122 This is in the realm of reasonable, and likely easy to solve with custom
 123 inbound addresses and Herald rules, or with a small extension to Herald. We
 124 might try to improve the documentation to make the feature easier to discover
 125 or understand.
 126
 127 You could (and should) go even further than this and explain why tasks need to
 128 be tagged with specific projects. It's very easy to provide more context and
 129 can only improve the speed and quality of our response.
 130
 131 Note that this solution (Herald rules on inbound email) has nothing to do with
 132 the narrow feature request (keyboard shortcuts) that you otherwise arrived at,
 133 but there's no possible way we can suggest a solution involving email
 134 integration or Herald if your report doesn't even mention that part of the
 135 context.
 136
 137
 138 Additional Resources
 139 ====================
 140
 141 Poor problem descriptions are a common issue in software development and
 142 extensively documented elsewhere. Here are some additional resources describing
 143 how to describe problems and ask questions effectively:
 144
 145   - [[ http://www.catb.org/esr/faqs/smart-questions.html | How To Ask
 146     Questions The Smart Way ]], by Eric S. Raymond
 147   - [[ http://xyproblem.info | XY Problem ]]
 148   - [[ https://en.wikipedia.org/wiki/5_Whys | 5 Whys Technique ]]
 149
 150 Asking good questions and describing problems clearly is an important,
 151 fundamental communication skill that software professionals should cultivate.
 152
 153
 154 Next Steps
 155 ==========
 156
 157 Continue by:
 158
 159   - returning to @{article:Contributing Feature Requests}.