VISUAL BASIC IS A TINKERER'S DELIGHT, but the illusion of Windows programming as child's play soon wears off. Programming in VB is still programming, and the basic problems of specification, design and documentation remain. Many VB evangelists discover to their cost that RAD is just a new name for 'breaking the rules'; nevertheless, the evolutionary approach of modern development techniques demands greater flexibility in the handling of specification and design. Enter Vision StoryBoard, an integrated documentation tool that matches the Visual Basic way of programming. StoryBoard's philosophy is a simple one: by providing the tools inside the Visual Basic environment, it offers the kind of flexibility VB programmers have come to expect, on terms they can understand. StoryBoard extends the idea of code commenting to the visual components of your programs, capturing information across the project lifecycle from initial design to testing and user documentation.

The heart of StoryBoard is SpecMaker, a visual commenting tool that allows you to attach notes to controls on your forms: you click on a control, and SpecMaker's floating dialog changes to show any notes you've already entered for that control. Comments can be entered under a number of categories, and you can add new categories or tailor the standard ones to suit your project's documentation plans. The standard categories are things like 'Functional Description', 'Requirements' and 'Testing notes', and each has its own field in the SpecMaker dialog. The comments are stored in a database which can then be accessed by the other StoryBoard components.

Once you've entered your comments into SpecMaker you can move on to work with one of StoryBoard's presentation modules. The first of these is SlideShow, which you use to build a set of annotated screen-shots from your application. This is where the product gets its name because the results are very much like the storyboards used by film makers. StoryBoard will build a default slide-show by leading you through a menu to choose which forms you want to include and then capturing a screen-shot for each one. You are also prompted for a SpecMaker comment category ('Functional description', for example), and StoryBoard uses the comments you entered to annotate the slides. You can then go on and edit the slides, linking them together by defining 'hot spots' on the pictures. Your finished slide-show has two purposes: you can use it to illustrate a presentation about your project, or StoryBoard can incorporate the slides into its documents.

The second of StoryBoard's presentation modules is the document generator, which takes your SpecMaker comments along with any slides you have generated and builds documents from them. You can choose what type of document you want, and StoryBoard changes the focus by selecting annotations from the appropriate SpecMaker categories. The document types are fully configurable, and the defaults have names such as 'Functional Specification' and 'Requirements Specification', based on the corresponding SpecMaker categories. You can tailor the formatting to some extent, but essentially the documents are all the same: a screen shot followed by a table of controls and then a section listing selected notes for each control.

Starting with version 4.02, StoryBoard also lets you generate a rudimentary Help file from a nominated document category. You choose which category to use for the Help texts (or add a new category), and you define the Help Context Id in SpecMaker. You can also choose to filter out particular control types (labels, for example) from the Help file and you can have StoryBoard omit entries for controls you haven't documented.

That's the theory, so let's see how it all works in practice. Figure 1 shows SpecMaker alongside the form I chose to work with. This is a modestly complicated form with around three times as many controls as the one used in the tutorial, and I annotated all controls in the 'Requirements' category. I then went on to SlideShow to make a slide for the form.

Figure 1 - Storyboard in action

Figure 2 shows my slide, and the first thing you will notice is how crammed it is. Although I kept the annotations relatively terse, they barely fit onto the slide -- and only then after a lot of reformatting by hand. You can add new boxes and arbitrary text by hand using the slide editor's rudimentary drawing tools. You can also configure which types of control are annotated by the slide builder, and you can control whether the annotations are copied from SpecMaker by clicking the 'annotate in slide show' check box on the SpecMaker dialog.

Figure 2 - Pushing the limits of SlideShow

StoryBoard 4 is essentially StoryBoard 3 re-coded for Visual Basic 4. It's a 32-bit application that requires Windows 95 or NT, and it only works with the Visual Basic Professional or Enterprise editions. Apart from the new Help file generator there are no functional changes and versions 3 and 4 currently share the same manual. Although Vision have smoothed off a few rough edges, the new 32-bit StoryBoard is compromised by a poorly-implemented user interface.

As StoryBoard's workhorse application SpecMaker's primary operating mode should be to run alongside VB to capture your notes as you develop your forms, but in practice StoryBoard's way of intercepting Visual Basic's mouse input for its own purposes makes it clumsy and intrusive. When you click on a control the focus switches to SpecMaker so you can type a comment, which means that if you want to ignore SpecMaker while you just play around with controls you have to click twice each time to make the focus stay with VB. This is annoying in itself, but it's compounded by the fact that over-zealous mouse clicking will dump you into a code window.

SpecMaker tries to emulate the behaviour of VB's Properties window by picking up the current control and switching the focus to itself when you start typing. In doing so it masks that behaviour so you can't use it, but it also introduces implementation artefacts that get in the way. Because the focus is with SpecMaker, VB's menus aren't available from the keyboard so, for example, if you're in the habit of hitting ALT-F, V periodically to save the project, nothing will happen. Even worse, simply dragging controls around the form doesn't work properly and leaves ugly graphical ghosts everywhere. In this respect StoryBoard 4.02 is a vast improvement over 4.0 (which was unusable) but it's still not satisfactory. Incidentally, closing SpecMaker doesn't help because it just hides the window and continues to intercept VB's mouse events.

Despite the problems there's no doubt that SpecMaker is a useful tool. It allows multiple developers to work with the same VB Project, and maintaining the comment databases as part of your source code can add real value. The need for slide shows is harder to fathom, but StoryBoard's main purpose is to generate documents. Like many document generators, StoryBoard tends towards massively verbose reports, and there is a danger of producing token documents that nobody will read. The application featured in the tutorial has only five forms, yet it generates a 29-page Functional Specification that is mostly structure with very little content. This is to be expected, because the quality of the final document relies entirely on the quality of the annotations entered into SpecMaker and the tutorial is a form-filling application that requires no complex commenting. Unfortunately, if you're going to use SlideShow it's almost mandatory to enter terse notes that do little more than echo the control names, and such token comments are as useless in printed reports as they are in program code.

SpecMaker's simplistic approach to documentation capture means that comments can only be added on a per-control basis. This means you can't say anything about the behaviour of groups of controls, a point that is underlined when you try to annotate a real application -- for example, there is very little you can usefully say about testing on a control-by-control basis. You can cheat by grouping controls with fake containers (panels, frames, etc.), but apart from gratuitously wasting resources this is unsatisfactory because it doesn't change the hierarchical structure of StoryBoard's reports. The crude way in which StoryBoard manages its database can also be restrictive: for example, although you can change the titles of SpecMaker's annotation categories, doing this after you've entered comments simply orphans the comments  they don't appear under the new heading, but they are still in the database because changing the title back (or adding a new one with the old name) retrieves them.

Looking at StoryBoard in a wider context, the notion of building specifications by designing the application is a curiously circular one. For small interactive development cycles building the specifications alongside the application itself may be useful way to proceed, but it's anathema to the traditional notion of a specification. Who is going to use StoryBoard? Not the people who write Functional Specifications or high-level design documents, because they probably haven't even heard of Visual Basic. And not the programmers, because they aren't qualified to write specifications. In targeting specification writers StoryBoard seems to mix up roles and blur the edges between specification, design and programming. This may be sound for a small-scale VB-only development but not for larger projects where Visual Basic is just one cog in a greater machine.

StoryBoard is ultimately disappointing. As a visual commenter it carries the germ of a good idea but the poor implementation is too intrusive. The need for slide-show presentations in the development cycle is questionable, but if they are required then StoryBoard offers little that can't be done better with Visual Basic itself: adding trivial VB code to your forms provides the linking that SlideShow implements with hot-spots on its slides, and the fact that you need Visual Basic to run your slide-shows (StoryBoard is a VB add-in and won't run standalone) simply emphasises this redundancy. If that isn't enough, SlideShow's crude user interface makes manual editing tiresome  and in practice you will always have to edit your slides by hand because the auto-generated slides are awful. The lines cross over each other, they don't terminate in the right places and the boxes are invariably the wrong size for the text. The annotation boxes can be dragged and resized in the slide editor, but they all start out the same size regardless of the amount of text. Screen redrawing is unreliable when boxes are moved or resized and the lack of a hyphenation feature wastes valuable real estate in the text boxes. You may also notice that the slide shows my form in a different colour, so presumably StoryBoard is stripping the palette to 16 colours. If we admit a simple drawing program or a presentation package such as PowerPoint to the equation, SlideShow offers feeble competition.

StoryBoard seems to work best as a rough-out tool for small projects or highly localised components of larger projects. Essentially it supports documentation of things that already exist, which begins to make more sense if you substitute the word 'description' wherever the StoryBoard manual says 'specification'. It's great for adding specific technical notes to your application's user interface, which has important implications for maintenance work, and it's also a useful tool for the programmers to use during development.