A manual isn't particularly useful on its own, since it's full of implementation details for one particular widget. SPJ is emphasising that details and descriptions of implementations should be avoided in favour of ideas and intuitions.
A purely theoretical paper can still be useful. It's even more useful if it's followed up by an experimental paper demonstrating or refuting the idea.
For example, it's silly to write a manual "How to use Google", then make Google. It's very sensible to write a paper "A proposal for improving Web search with mutual-popularity measures", then try to make Google. If Google succeeds, we can write "Mutual-popularity measures and Web search: large-scale experimental results". If it fails, we can write "Scaling issues on the Web: impacts on mutual-popularity algorithms".
Skilled programmers use different techniques to this end: some write a first version and throw it away, some write extensive manual pages or design documents, others fill out a code template where every requirement is identified and assigned to a specific function or comment. For example, in Berkeley DB, we created a complete set of Unix-style manual pages for the access methods and underlying components before writing any code.
Breaking with this sort of practice is exactly why agile development and it's ilk were born.
While writing a formal specification can be useful, it is rarely as useful as defining the problem and placing your solution in the context of other possible solutions.
I've been lucky enough to attend one of Peyton Jone's talks in person. He is not suggesting to "write a formal spec" before you do research. In contrast, his attempt is to be agile: keep going back and forth in the paper writing as you do research. Only then you will see what's missing.
Essentially, what he is suggesting is actually "agile academic research", compared to the "waterfall academic research" (do stuff, then write-up a paper with what you've got...)
Comments
Idea - Write manual - Make program
A manual isn't particularly useful on its own, since it's full of implementation details for one particular widget. SPJ is emphasising that details and descriptions of implementations should be avoided in favour of ideas and intuitions.
A purely theoretical paper can still be useful. It's even more useful if it's followed up by an experimental paper demonstrating or refuting the idea.
For example, it's silly to write a manual "How to use Google", then make Google. It's very sensible to write a paper "A proposal for improving Web search with mutual-popularity measures", then try to make Google. If Google succeeds, we can write "Mutual-popularity measures and Web search: large-scale experimental results". If it fails, we can write "Scaling issues on the Web: impacts on mutual-popularity algorithms".
It would indeed be silly, since Google is not a program.
Google’s search engine, however, is, and it would be perfectly sensible to first write a manual for a search engine before implementing it.
From http://aosabook.org/en/bdb.html:
Skilled programmers use different techniques to this end: some write a first version and throw it away, some write extensive manual pages or design documents, others fill out a code template where every requirement is identified and assigned to a specific function or comment. For example, in Berkeley DB, we created a complete set of Unix-style manual pages for the access methods and underlying components before writing any code.
Which is the 3rd circle of hell.
Breaking with this sort of practice is exactly why agile development and it's ilk were born.
While writing a formal specification can be useful, it is rarely as useful as defining the problem and placing your solution in the context of other possible solutions.
I've been lucky enough to attend one of Peyton Jone's talks in person. He is not suggesting to "write a formal spec" before you do research. In contrast, his attempt is to be agile: keep going back and forth in the paper writing as you do research. Only then you will see what's missing.
Essentially, what he is suggesting is actually "agile academic research", compared to the "waterfall academic research" (do stuff, then write-up a paper with what you've got...)