Re: Workbench 2.0, One Assessment
- To: mathgroup at smc.vnet.net
- Subject: [mg108308] Re: Workbench 2.0, One Assessment
- From: David Bailey <dave at removedbailey.co.uk>
- Date: Sat, 13 Mar 2010 07:56:54 -0500 (EST)
- References: <hndb1q$dd4$1@smc.vnet.net>
David Park wrote: > 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. > Thanks for that very detailed exploration of the Workbench and the DC. [rant] I must say, I am not a fan of creating layers of hidden information by GUI - which is why I extracted the basic steps required to create DC documentation, just using Mathematica. These are available on my website. I think it is always a mistake to take API's and hide them behind a GUI - without providing access to the underlying API. The problem is that people's requirements vary, and it is very restrictive to be forced into someone else's template. I would also question whether it is really desirable for third party documentation to fit exactly the same template as that used by WRI. I think it is nice to be able to see immediately that you are viewing Blogg's package documentation rather than a system page. I have never understood the design of the new documentation centre. The old help system (version 5.2 and earlier) relied entirely on text files (BrowserCategories.m) to provide linkage information. It is true that the old system did not provide the same search facilities, but some equivalent of (Update Help Index) could have converted textual information into whatever binary file structure was required. Indeed, considering the time that it takes to look up anything in the DC, it is hard to believe the search strategy used by the DC is highly optimised - GOOGLE is often faster, working over the internet! Wolfram Research seemed to have learned long ago that hiding information inside binary files is generally a bad idea. Thus notebooks used to be binary files, until Version 3, after which they became textual - and I doubt anyone would argue that this was a bad decision. The DC however, regressed to using binary files to hold indexing information with obscure names such as _0.cfs - one might ask why! [/rant] David Bailey http://www.dbaileyconsultancy.co.uk