Several instances of what I consider "ill-design".
1) WRI has not thought out the process of having multiple packages within a single Application. There is often convenience in grouping routines into different sub-packages even though this grouping might not be perfect from a "computer science" perspective. The logic of the BeginPackage statement is not correctly designed. The second argument or "needs" portion of the statement should not be establishing definitions from the `Private` section of the needed package. It should only be establishing the exported symbols. The only `Private` definitions that should be established should be from the first argument of the BeginPackage statement. It doesn't seem to me that this would be difficult to implement. WRI is under the impression that going to multiple files but putting all symbols in a single context will solve the problem of symbols going mistakenly into the `Private` context. This is false. It has nothing to do with the context of exported symbols. It has to do with the order and unnecessary establishment of routine definitions from `Private` sections of packages. (To avoid the problems in my current project I went back to a single package file.)
2) I always develop routines in regular Mathematica, outside of Workbench, and when I think they're ready I move them to the Workbench files. Nevertheless, I sometimes find that I want to modify them later. (One of the advantages of writing Function pages is that if one finds it difficult to explain a routine or generate meaningful examples then it is a sure sign that the routine is ill-designed.) So I sometimes find that I'm temporarily debugging and testing on a Function page. Or this could be done in a regular notebook in the Workbench folder. But if one evaluates a << package` statement within Workbench it doesn't load the Workbench package files; it loads the files from the currently deployed package. It does this even though I set the Version number in Workbench to a higher value. What sense does it make to have code files in Workbench where we can modify them if when we reload the package it uses the unchanged deployed version? One can use the "Run Package" button but with multiple packages we may want to just reload the entire Application. And the "Run Package" method does not work if one uses the WRI method of multiple files with a single context.
3) WRI tries to force users into the box specially designed for their own documentation: Guide pages, Function pages and Tutorial pages. But user Application projects will often take a distinctly different coloring. Specifically, they may want folders with notebooks in their own style sheets - say a book, or papers or lessons or tutorials done in their own style. These may be the larger part of the total content of the Application. Although it is possible to make some links "by hand" I believe the general linking and indexing process does not handle this.
Several instances of "shoddily implemented ".
1) I believe that in Workbench 1 there was a facility for automatically generating Function page tables for a routines Options. This no longer works in Workbench 2 and it has to be done by hand.
2) CellID seems like a good idea and Workbench has links to CellID. However, if the linked cell is in a closed section or lower level subsection the notebook is not opened to expose the cell. So the reader still has to search for it. Links to Cell Tags does expose the actual cell. But it's easier to make links if one doesn't have to establish a long list of cell tags.
3) The user is hit with a number of warning messages when first using the DocumentationTools Palette - something about StyleNames. And the PacletInfo.m files shows warnings even though one is following the WRI recommendations.
4) The whole matter of using multiple packages is not properly implemented but that is partly a design fault.
So "shoddily" is probably an overstatement and I apologize for that. Much of Workbench does work but there is a high standard needed to entice more users to embrace the Application approach and I believe there is a much larger group of users that would benefit from it.
Instance of "neglect".
My Workbench 2 version does not appear to be dated but it seems to me that it's been over two years since there has been an update. As far as I know, none of the issues concerning user Applications, as opposed to internal WRI documentation, are being considered or addressed. Also, there is the issue of long term stability. Users will be hesitant to work within the Application paradigm if they are not confident they are working in a stable environment. This means it needs serious initial design with strong feedback and not just casual in-house design.
I wouldn't complain about it if I didn't think that WRI was basically on the right track. I just wish they would finish it and polish it.
From: Michael Weyrauch [mailto:email@example.com]
I understand that the critisism of David Park points mainly to documentation creation, but that does not justify to call the whole system "ill-designed, neglected and shoddily implemented". I cannot see that.