Workbench 2.0, One Assessment
- To: mathgroup at smc.vnet.net
- Subject: [mg108278] Workbench 2.0, One Assessment
- From: "David Park" <djmpark at comcast.net>
- Date: Fri, 12 Mar 2010 07:11:53 -0500 (EST)
Finally, after almost three years we have a documentation system for the Documentation Center with Workbench/DocumentationTools. It is adequate and one can organize projects and do documentation, but if I had to grade it I would give it a B-. The main problem is that Workbench and the documentation tools were initially, and for some time, tuned up for the internal needs of WRI and their particular documentation protocol. There is a significant difference between that usage and what a typical user might require and expect. I hope that we might have an improved Workbench 2.0.1 with much less delay than 2.0. First I want to describe what I see as a typical user project and then I'll discuss some of the problems that exist. A typical project might be a research project in some field that includes one or more packages, a folder containing a book consisting of multiple notebooks, perhaps a folder of special purpose papers, perhaps another folder of lesson exercises for a course being taught on the field. There would be a main guide page for the entire project that might be organized in various ways depending on the extent of the material. It might branch off to a separate Guide page for the package documentation. It might have Sections containing table of contents for the book, papers and lesson exercises - or these might be on separate Guide pages. The book, papers and lesson plans might each have their own style sheets. There might be multiple packages as a convenient way to group and organize routines. But the routines in all the packages will be part of a single paclet that is associated with the application. The deployed application could contain a Workbooks (say) folder and possible subsidiary folders that contained working and developmental notebooks. Thus the user would spend most of his time working in the regular Mathematica environment and only go to Workbench when some developmental work was ready to be incorporated into the "finished" part of the application. Updating the application would not overwrite the Workbooks. If the user sent the application to someone else, he might remove the Workbooks. This is a very convenient way of doing serious professional work because it organizes, documents and preserves your work. It is not just a lot of notebooks and routines scattered around. Where is that graphic I did a month ago? Which notebook had that routine I did a year ago and how does it work? Was it updated in some subsequent notebook? Using documented Workbench applications is extra effort, but is the product of your work worth the effort? I think so. The finished work is both in your deployed application and in the Workbench files so it is a type of backup. Also, it presents the standard Mathematica interface to any users of the application. Why should you design your own organization and interface when a standard one is already provided with features that might be difficult for your to duplicate? But this will not work unless the software is perfected, it is easy to learn and intuitive, and the experience is smooth. I don't think it is quite there yet. Also WRI must make a firm commitment to Workbench/DocumentationTools so that users will know that their own applications will not go out of date in a few years. It means that it has to be carefully thought out and designed from the start. Some of the current problems I've seen, in no particular order: 1) Packages must be loaded on Function pages. It would be desirable that the packages be loaded only once on a Function page. With the present design, the package(s) must be loaded in every grouping on Input cells used on the page. I don't see why this is because everything imported by the package has its own package context. Apparently when a Function switches the CellContext it throws away all knowledge of previously defined items, including imported package names. One can switch the Function page context to Global` but then one of the extremely nice features of the Function pages is lost - noninterference of Help pages with regular notebooks. One should be able to use a Notebook Context but this appears not to work correctly. 2) The Guide page design is too restrictive. It should have more of the regular notebook styles such as regular Sections, Subsections etc. Even the styles that they have do not show up on the right-click context menu. User's should have more freedom in designing the main Guide page. It is, after all, the principal interface a developer presents to users and readers. The WRI Guide page style just does not port over well to major user designed applications. Come to think of it, WRI doesn't even use it for their main guide page. 3) There is a new feature that is rather nice, but again far too restrictive for a typical application. This is an Overview page that is a special form of a Tutorial page. The idea is that a package may have a number of tutorials written with the Tutorial style sheet and all in the Tutorials folder in the documentation. Then you can create an Overview page that will contain a table of contents for the notebooks in the Tutorials folder. It goes down to the various sectional levels and provides direct links. An example of this is the tutorial/NDSolveOverview in the DC. This is nice but we can't generate Overview pages for folders other than the Tutorial folder or for non-Tutorial style sheet notebooks. What about our Book folder in the typical project or the Topical Papers folder or the Lessons folder? (This can be done but only by making each entry by hand.) Also it would be nice if a table of contents could be generated and then pasted under a main Section in the main Guide page. So the main Guide page might have a Packages section, a Book section, a Topical Papers section and a Lesson Exercises section and within the last three there would be TOCs. 4) Workbench does allow the developer to include folders parallel to the Tutorials folder, such as the Book, TopicalPapers and LessonExercises. But these are second class citizens. The DC will not, for example, search on keywords in notebooks with their own style sheet. This is presumably because the documentation style sheets have a Categorization section at the top that contains paclet information about the notebooks, including key words. This section appears in the source notebook but not in the deployed notebook. Perhaps there would be a method for making this style available to other style sheets. And, as mentioned above, Overview does not work on these notebooks. There are a few things that will just catch up users. Two of these are: 1) You can have multiple packages in one application. You would end up with the usual binary naming scheme such as MyApplication`Package1`, MyApplication`Package2`, etc. But then Mathematica/Workbench will not work correctly to add the Function page links at the end of the usage messages. This requires extra specification in the PacletInfo.m file that is not yet documented. (It probably will be in the next release.) 2) If you open a notebook in one application and then switch to do documentation on a second application DocumentationTools will wrongly make all the links (for example See Also links) to the first application paclet. You might not even be aware of this. This happens even though the source notebook clearly contains information telling what paclet it is associated with. (I inadvertently did this when I wanted to first check to see how I did something on another application.) Having the link paclet be determined by the first notebook opened in a Workbench session is not good design. It is very welcomed to have Workbench/DocumentationTools available. It does work for basic documentation. But you can waste a lot of time fighting its "features" and the basic technology is not yet organized in the best way to write major applications. David Park djmpark at comcast.net <http://home.comcast.net/~djmpark> http://home.comcast.net/~djmpark/