I would like to make a few suggestions for Workbench and the writing of applications. I believe they accord with the way users doing significant research or development might work. It would be very nice if they could have a straightforward, clear and intuitive method to organize their work. There is a way to do this, which is 95% in accord with procedures WRI has already established. It is amazing how few people actually follow it. A few improvements would make things easier for users. The following is what I would advise to users and how Wolfram developers could make a few improvements.

I would advise any user who is embarked on a significant project (a course of study on some subject matter, a research project, creating analytic tools to support some project and similar tasks) as follows: Put your project in a UserBaseDirectory/Applications/yourProjectName folder. (I don't know how to type that in using a dollar sign.) It is very difficult to get users to do this! They have all kinds of reasons for not putting a project there, none of them sufficient. One reason I get is: that’s a place WRI puts their packages. Not true. But they get this idea because some WRI applications are combined with private applications in the “Add-ons and packages” button on the main Wolfram documentation page. I would suggest that button should be renamed “Private Applications” and the WRI packages be moved to “Standard Extra Packages”. Then it would be much clearer to users that they had a definite home for their own applications.

It would also be useful for users to distinguish more clearly between “applications” and “packages”. An application is the primary concept. An application may not have any packages, or it may have a number of packages. But packages should always be within applications, and private applications should always be at UserBaseDirectory/Applications.

The idea is that a user could start off an application in a simple way. A user does not at first have to understand everything about developing a full-fledged application. It might start as a place to put notebooks related to a particular subject matter. Almost any serious project will eventually lead to specialized routines. At first these might be in notebooks, and copied from one notebook to another. Eventually the user could move them to a package. It is really easy, but maybe a small speedbump for a new user. Then later a user might want to add his own stylesheet. And perhaps some palettes. And then finally, if the user wants it, Wolfram style paclet documentation. Each of these requires some additional skills, but they are not horribly difficult and if you start out correctly everything is in place for adding these extra application features as you are ready – with minimum effort. The user might say he doesn’t know how to do those things so his work doesn’t deserve to be in the user Applications folder. Yes it does deserve to be there. If nothing else, it gives a way to organize your work. And it provides a smooth path to full-fledged applications.

So this is how a folder structure for an application would look, even if many of the folders are initially empty:

$UserBaseDirectory/Applications/MyApplication/
        Documentation
        Kernel (init.m)
        FrontEnd
            Palettes/MyApplication (palettes)
            StyleSheets/MyApplication (stylesheets)
        MyApplicationNotebooks (development notebooks etc.)
       packages…

The reasons for having this structure are as follows:

1) If there are packages, they can all be loaded simply with << MyApplication`. Mathematica will then automatically evaluate the init.m file, which in turn should contain code to load each of the packages and any other initialization you wish.

2) Mathematica automatically looks in UserBaseDirectory/Applications for the application, the packages, stylesheets and palettes. The stylesheets will automatically appear on the Mathematica menu, Format, Stylesheet list. Similarly the palettes will automatically appear on the Mathematica menu, Palettes. They will appear there even if you have no packages or documentation. You don’t have to do anything else to install them. The reason for the extra MyApplication folder level in Palettes and StyleSheets is to keep all of your stylesheets and palettes together under a single heading in the Mathematica menu. It is much neater, better identifies them, and doesn’t clutter up the Mathematica menus. And if you send your application to someone else it doesn’t clutter their menus.

3) If you zip and send MyApplication to someone else all they have to do is unzip it into their UserBaseDirectory/Applications folder and everything works.

It might be nice if Mathematica had a routine CreatePrivateApplicationStructure that would automatically create the folder structure. This might encourage more users to follow this path.

Now for doing paclet documentation and using Workbench 3. An application may have been rather fully developed within Mathematica, without using Workbench. Some people may disagree with what I recommend now if they want to use really advanced features of Workbench. However, I’m using Workbench for the sole purpose of producing documentation. I can do development and debugging in regular Mathematica. I have no problem in debugging simply by inserting temporary Print statements into routines. So I don’t upload any of my package code, stylesheets or palettes to Workbench. This has the advantage that I don’t have to keep two sets of files in sync. When an application is Deployed from Workbench, existing files are overwritten. If you changed code or any of the other items you would lose the changes if you forgot to copy them to Workbench. We only want the documentation pages to be rewritten.

However, Workbench 3.0 does not allow one to directly do that. It’s possible to fake Workbench out and get what one wants but my argument is that it should not be necessary to do that. It should work cleanly and as expected. Should some biochemist (say) working on modeling a piece of metabolism be expected to become an expert in faking out Mathematica Workbench? To me it seems that this would be easy to fix and WRI should fix it. Here’s what happens. When one tries to Deploy the documentation, Workbench says that there is no Wolfram Language Application and will not do the automatic Deploy. Instead, one has to do a Manual Deploy. And that has lots of problems. For example, the PacletInfo.m file gets deployed to the Applications folder and not to the MyApplication folder. So the user would have to move it. Then the documentation gets deployed into a new folder named after the Workbench project and not to the application folder. So that would also have to be moved by hand.

It turns out that there is only one necessary file to have a Wolfram Language Project and that is an init.m file. But why should that be required? It means one has to manually keep that file in sync. It has nothing to do with documentation. So why couldn’t WRI eliminate that requirement? It’s possible to deselect the init.m file from deployment. Then all that is left are the empty folders for stylesheets and palettes. That all works as long as one doesn’t slip up and deploy an out-of-sync init.m.

It would be much simpler if Workbench had a Documentation Only checkbox, or have Workbench automatically detect that there are only documentation files and do an automatic straightforward deployment of them – with no choices of any other files to be deployed.

Another problem with Workbench is the form of the PacletInfo.m file. With Workbench 2, I was instructed (by an insider at WRI) to use a given form. That may have had to do with using multiple packages in the application. In any case, I don’t really know why the form is as it is, and it shows warning messages within Workbench. But one can just ignore them. Nevertheless, how does this look to a typical user? This should be cleaned up with a clear form for the kind of project I’ve been describing. And no warning indications.

Finally I would like to mention one other issue that has to do with applications that contain multiple packages. The packages may be written by various people, or organized around various functionalities. The present paradigm with Mathematica is to require a rigid tree-structure for package routines. If package A requires package B and package B requires package A, one can get into trouble because some routines may not yet be known at the time Private code is read in and hence go into the Private` context. This seems to me to be unnecessarily restrictive. There is a very simple alternative. Put all public export statements in one or more package files that have empty Private sections. Put all the code in one or more package files that have empty public sections. Put everything into a single application context. Then in the init.m file read all the public export files first, then read the Private code files. Then do various other initializations, such as Protecting exported symbols. It would be nice if Mathematica had a mechanism to specify that only the public or only the Private portion of a normal Package file were to be read. Then it wouldn’t be necessary to separate them into separate files. The dependency argument of the BeginPackage statement wouldn’t be necessary. I’ve been using this method of separating the Private and Public sections without any difficulty on a rather large project.