This paper was mentioned on a recent Stack Overflow podcast and while it deals explicitly with writing a philosophy paper, it is a good read for testers as well. Since I can see the click-out rates from the analytics I know that they are pretty bad so I’m doing the Coles Notes version here.

It starts out immediately with a ‘context matters’ blurb:

Most of the strategies described below will also serve you well when writing for other courses, but don’t automatically assume that they all will. Nor should you assume that every writing guideline you’ve been given by other teachers is important when you’re writing a philosophy paper. Some of those guidelines are routinely violated in good philosophical prose.

I think a lot of prescriptive books out there should begin with a warning like this.

So what should a philosophy paper include? Well, a reasoned defense of some claim according to the author who then gives some examples. Now think about this in the context of a bug reports. Essentially the same guidelines apply.

Once you have your thesis (This is a bug because it violates the internal consistency oracle), you then develop it by:

  • Criticize that argument or thesis
  • Offer counter-examples to the thesis
  • Defend the argument or thesis against someone else’s criticism
  • Offer reasons to believe the thesis
  • Give examples which help explain the thesis, or which help to make the thesis more plausible
  • Argue that certain philosophers are committed to the thesis by their other views, though they do not come out and explicitly endorse the thesis
  • Discuss what consequences the thesis would have, if it were true
  • Revise the thesis in the light of some objection

Now read the bullets above while mentally swapping out ‘bug’ for ‘thesis’. Still a pretty good fit.

Two other attributes of a paper are:

  • A good philosophy paper is modest and makes a small point; but it makes that point clearly and straightforwardly, and it offers good reasons in support of it – No Fluff, Just Stuff. IEEE 829 be darned. The length something ends up being is exactly the length it should be.
  • Originality – The nugget in this section is Your critical intelligence will inevitably show up in whatever you write.

Now that we know what should be in the paper, Major Guidelines are given:

  • Make an Outline – Make your checklists ahead of time as well as inventory the heuristics you think might apply to this testing task. Rarely do we do our best work under stress so if you can give yourself any chance of working more effectively it should be taken. This is the primary reason I do any sort of pre-test planning.
  • Make the structure of your paper clear – Focus any documentation at the correct audience; Your reader shouldn’t have to exert any effort to figure it out.
  • Be concise, but explain yourself fully – It would be rather ironic to explain this one aside from Nothing should go into your paper which does not directly address that problem and take special pains to be as clear and as explicit as you possibly can.

Those guidelines are nicely summarized as follows:
In fact, you can profitably take this one step further and pretend that your reader is lazy, stupid, and mean. He’s lazy in that he doesn’t want to figure out what your convoluted sentences are supposed to mean, and he doesn’t want to figure out what your argument is, if it’s not already obvious. He’s stupid, so you have to explain everything you say to him in simple, bite-sized pieces. And he’s mean, so he’s not going to read your paper charitably.

The rest of the paper is pretty domain specific but does have a couple nuggets in it:

  • Try to anticipate objections to your view and respond to them
  • Your paper doesn’t always have to provide a definite solution to a problem, or a straight yes or no answer to a question
  • It’s OK to ask questions and raise problems in your paper even if you cannot provide satisfying answers to them all
  • There’s no need to warm up to your topic. You should get right to the point, with the first sentence.
  • You may use the word “I” freely, especially to tell the reader what you’re up to
  • Even professional philosophers writing for other professional philosophers need to explain the special technical vocabulary they’re using. Different people sometimes use this special vocabulary in different ways, so it’s important to make sure that you and your readers are all giving these words the same meaning. Pretend that your readers have never heard them before.
  • Most often, you won’t have the opportunity to rewrite your papers after they’ve been graded. So you need to teach yourself to write a draft, scrutinize the draft, and revise and rewrite your paper before turning it in to be graded.

So good. Though, the tester in me feels compelled to point out that the html, specifically the ol tags appear to not be coded correctly in the paper.