MathGroup Archive 2010

[Date Index] [Thread Index] [Author Index]

Search the Archive

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/  


  • Prev by Date: Re: Trouble with coupled quadratic equations where the solutions are degenerate/symmetric
  • Next by Date: Re: plot solution derivative
  • Previous by thread: Re: Trouble with coupled quadratic equations where the solutions are degenerate/symmetric
  • Next by thread: Re: Workbench 2.0, One Assessment