Differential D25007 Diff 23 src/docs/contributor/describing_problems.diviner

Changeset View

Standalone View

src/docs/contributor/describing_problems.diviner

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

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

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

	> My company does contracting work for government agencies. Because of the			(NOTE) My company does contracting work for government agencies. Because of the
	> nature of our customers, deadlines are critical and it's very important			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			for us to keep track of where we are on a timeline. We're using Maniphest
	> to track tasks...			to track tasks...

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

	> We work on a large server program which has very long compile times.			(NOTE) 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			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			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, ...			`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			(NOTE) I triage manual test failures from our offshore QA team. Here's how our
	> workflow works...			workflow works...

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

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

	> {icon times color=red} Add custom keyboard shortcuts.			(IMPORTANT) Add custom keyboard shortcuts.

	> {icon times color=red} I have a problem: there is no way to download			(IMPORTANT) I have a problem: there is no way to download
	> .tar archives of repositories.			.tar archives of repositories.

	> {icon times color=red} I want an RSS feed of my tokens. My root problem is			(IMPORTANT) I want an RSS feed of my tokens. My root problem is
	> that I do not have an RSS feed of my tokens.			that I do not have an RSS feed of my tokens.

	> {icon times color=red} There is no way to see other users' email addresses.			(IMPORTANT) There is no way to see other users' email addresses.
	> That is a problem.			That is a problem.

	> {icon times color=red} I've used some other software that has a cool			(IMPORTANT) I've used some other software that has a cool
	> feature. Phabricator should have that feature too.			feature. Phorge should have that feature too.

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


	"5 Whys" Technique			"5 Whys" Technique
	================			================

	▲ Show 20 Lines • Show All 77 Lines • Show Last 20 Lines