@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Provide documentation explicitly describing what a "root problem" is
Summary:
A guide to basic skills every software professional should have.
This is so fundamental that I don't think the document is actually helpful, but we can try it I guess.
Test Plan: Reading?
Reviewers: chad
Reviewed By: chad
Subscribers: Shredder121
Differential Revision: https://secure.phabricator.com/D14707
+163
+159
src/docs/contributor/describing_problems.diviner
+159
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 effectivey:
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:Contribuing Feature Requests}.
+4
src/docs/contributor/feature_requests.diviner
+4
src/docs/contributor/feature_requests.diviner
···
173
173
will not accept feature requests which do not contextualize the request by
174
174
describing the root problem.
175
175
176
+
If you aren't sure exactly what we're after when we ask you to describe a root
177
+
problem, you can find examples and more discussion in
178
+
@{article:Describing Root Problems}.
179
+
176
180
177
181
Hypotheticals
178
182
=============