On Jun 6, 2013, at 8:19 PM, djmpark <email@example.com> wrote:
> The problem is that now the documentation methods are highly tuned for WRI's > own requirements. The Workbench procedures for users appear to be a spinoff. > They are not easily applied to the needs of Application development and use. > The present WRI package and user documentation facilities are ill-designed, > buggy, unintuitive and unstable. WRI has been dangling this out there for a > number of years. It's time to finish the job and do it right. > > > David Park > firstname.lastname@example.org > http://home.comcast.net/~djmpark/index.html
There is a certain irony to be noted in reading Stephen Wolfram's latest blog on the history of Mathematica regarding the importance of documentation for users of Mathematica who wish to develop applications and extensions of the system for use by the Mathematica community.
"Meanwhile, just as for SMP, I'd assembled a team, and started the actual implementation of Mathematica. I'd also started a company this time with me as CEO. Every day I'd write lots of code. (And to my chagrin, quite a bit of that code is still running in Mathematica today, especially in the pattern matcher and evaluator). But my biggest focus was design. And following a practice I'd started with SMP, I wrote documentation as I developed the design. I figured if I couldn't explain something clearly in documentation, nobody was ever going to understand it, and it probably wasn't designed right. And once something was in the documentation, we knew both what to implement, and why we were doing it."
Clearly Stephen recognized and embraced 25 years ago the importance of Documentation in software system development. The irony is that Mathematica users 25 years on feel facilities for producing their own package documentation do not match the exemplary standards of so much else that we admire in Mathematica 9.
There may well be a lot of Stephen's original code still in the Mathematica Documentation facilities which might explain David's valid criticism of the present WRI package and user documentation facilities.
Cheers .... Syd
Syd Geraghty B.Sc, M.Sc.
Mathematica 9.0.1 for Mac OS X x86 (64-bit) (January 24, 2013) Release ID 126.96.36.199 (4055646, 4055073) MacOS X V 10.8.2 Mountain Lion Mac mini 6,2 Late 2012 2.6 GHz Intel Core i7, 8 GB 1600 MHz DDR3 Graphics Intel HD Graphics 4000 768 MB