RogerBW's Blog

I think I have come up with a new and potentially useful paradigm for computer-related problem reports.

The report should consist of three parts:

1. I am trying to achieve X.
2. I am performing action Y.
3. Unexpected thing Z happens.

The Y and the Z constitute a conventional report, at least one that's been written by someone who understands that computers are not magic, at least not in the way they think of magic: "When I press foo I get an error message that says bar". X is also helpful.

Sometimes the X can be derived from the Y, and even the Y from the Z: if the program crashes when you save a file, it's pretty clear how to break it down. But it's beneficial to the problem-solver to have it all laid out, and it can be beneficial for the reporter to think about it too (hmm, it doesn't happen every time, only for files with spaces in their names).

Some problems lie in the X rather than the Y/Z. Many times I've seen a technical forum get into intricate details of exactly how to make a particular program act in a particular way, when a far easier solution to what the user actually wanted – which had never been mentioned – was actually to use a different program. (This is in the non-corporate Linux world, where software is, to a first approximation, free, and where a task will typically involve using a chain of different small programs rather than one huge one – it's not as if one were saying "use LyX instead of LibreOffice" and disrupting someone's entire working practices.)

And sometimes action Y will work perfectly well, except for a few obscure edge cases, which one won't tickle until one knows more about the state of the rest of the system when Y happens.