IBM®
Skip to main content
    Country/region select      Terms of use
 
 
   
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks  >  Lotus  >  Forums & community  >  Best Practice Makes Perfect

Best Practice Makes Perfect

A collaboration with Domino developers about how to do it and how to get it right in Domino

If you've been messing around with the version 8.0 Beta, you might have noticed that we added a couple of design elements, but these don't appear in the Design Synopsis output, and neither do many of the new options we've added to other design elements. This largely has to do with where we think the Designer team's time would be most effectively spent -- the perpetual issue of too much to do and wildly varying opinions on which things are most important.

But also, the Design Synopsis has never worked very well for large designs ("Too many paragraphs") or for large blocks of LotusScript , whose code does not appear in full. The most important limitation of the Design Synopsis, though, in my estimation, is that the output is not customizable. People want to use reports of the design for different things -- maybe someone is interested to see all the LotusScript code, while someone else is just wanting to know what all fonts are used so they can review corporate standards compliance, someone else wants every bit of any kind of code to see where a design element is referred to, and so on. Either the synopsis contains way more information than you want, or it doesn't contain the specific detail you were interested in.

DXL Transformer dialogThat's why, rather than put effort into updating a tool that has a basic conceptual drawback, some versions back we inserted a new function which we hope people will want to use instead. The menu item Tools / DXL Utilities / Transformer... causes your computer to change into a little robotic man who will attack your bugs with guns blazing...

No, wait, different reality. [Wrench!] Actually, it'll put up a dialog very similar to the Design Synopsis dialog, with one important difference: the opportunity to select an XML stylesheet (.xsl file) to transform the DXL descriptions of the selected design elements into human-readable form as an HTML file.

There's only one drawback -- IBM has only supplied one report format for you. The file REPORT-AllLSinForm.xsl extracts all the LotusScript code from Form design elements in the DXL and formats that source code into a nice report. So you are sort of on your own to create additional reports that capture the information you specifically want.

Fortunately, there are resources to help you. Many thanks to Christian Gorni, who has posted a couple of additional XSL files on openntf.org. These might be useful to you as is or with a little tweaking, or they can be examples for your own efforts. If you want to get your feet wet in editing others' XSLs or creating your own from scratch, people in the know tell me that XMLSpy is an excellent tool for that purpose -- free 30-day evaluation.

If there is some Domino developer out there with XSL skills and too much time on their hands, I would love to see a monster XSL file that basically reproduced the output of the Design Synopsis, so that people could just take out what they didn't want. Mr. Mac Guidera, perhaps?

Andre Guirard | 17 April 2007 03:14:00 PM ET | Caribou Coffee, Plymouth, MN, USA | Comments (1)


 Comments

1) Transformer missing...
Thomas Bahn | 4/17/2007 4:09:00 PM

Hi Andre,

do you know, why the Tools/DXL Utilities/Transformer is hidden, when the default browser (in the location) is not Internet Explorer? We do not use IE, so we cannot use the Transformer :-(

Thomas

tbahn@assono.de

{ Link }

2) thanks Thomas, was confused until I saw your post
Sean Cull | 4/18/2007 3:48:35 AM

it seems the anti blog spam thing means I need to add some words here

3) re: Transformer missing...
Andre Guirard | 4/18/2007 8:19:39 AM

[i]> do you know, why the Tools/DXL Utilities/Transformer is hidden, when the default browser (in the location) is not Internet Explorer?[/i]

Yes, I do know why. I just found out yesterday, in fact. Because, you see, we removed that restriction in 8.0, and that revealed that the display of the resulting HTML doesn't work unless IE is your browser. At some point, someone hid it rather than making it work with other browsers, I guess. I will see whether I can fix that little problem.

4) Design Synopsis
Bryan Schmiedeler | 4/18/2007 9:45:44 AM

Andre,

Your post was very enlightening.

"But also, the Design Synopsis has never worked very well for large designs ("Too many paragraphs") or for large blocks of LotusScript , whose code does not appear in full."

I have been working with Notes for 8 or 9 years now and this is *the* most annoying aspect of an otherwise outstanding application development platform - including features that don't work or only work under certain conditions. Several times a member of my team has called Lotus support to determine why something is not working only to be told that the method or class (or other feature) is buggy or doesn't work under certain conditions or whatever. This is just not acceptable. Either a) don't put the feature in or b) fix it or c) document the limitations in the help.

I cannot emphasis enough how strongly I feel about this. Review your post. A feature was introduced that had bugs. Instead of fixing it, a new feature was introduced that "we hope that people will want to use instead." But that feature has some limitations, one of which means it has been hidden when the default browser is not IE.

Question: how is someone supposed to know that you would rather they use Transformer instead of Design Synopsis?

Bryan Schmiedeler

5) re: Design Synopsis
Andre Guirard | 4/19/2007 11:14:03 AM

Bryan, I was a Domino developer for several years before I joined Lotus and was a prominent complainer, so I can appreciate your frustration. Of course, now I can see it from the other side also, and have experienced how these situations come about.

Several times a member of my team has called Lotus support to determine why something is not working only to be told that the method or class (or other feature) is buggy or doesn't work under certain conditions or whatever. .... Either a) don't put the feature in or b) fix it or c) document the limitations in the help.

Not having been involved in the original decision, I can only speculate on the reasons for it, but here are my thoughts:

The issue with the design synopsis has to do with the limits of rich text and probably of some internal memory buffers. At the time we design something, we may be aware of the limits, and make a call on whether the limit is acceptable or whether it's worth doing a lot of extra work to accommodate a wider range of situations. Sometimes, a limitation that seemed quite reasonable when it was originally put in the product, might prove insufficient several years down the road. Particularly when you're talking about an application like Notes, where people build applications on top of it, it's hard to predict what creative uses people will put it to. Who knew applications would get so big? It might seem obvious now, but everything that's already happened is obvious in hindsight.

A feature was introduced that had bugs. Instead of fixing it, a new feature was introduced that "we hope that people will want to use instead."

Creating software products involves making some tough decisions. Smart people to work on the product are a severely limited resource, and we always have to figure out where they are best to be deployed. We make the best choices we know how, and that might involve choosing between implementing three important features pretty well and hope to refine them in future releases as we discover how people want to use them, versus implementing one important feature in a way that will work in any situation we can imagine, however unlikely. Or, we can choose between implementing a new feature that everyone is begging for, or totally rearchitecting an old feature that was originally implemented in a way that hasn't worn well over the years, but that still works in nearly all cases.

Keep in mind that this particular old feature is limited anyway, in that the output can't be customized, and that there are partner products which do the same thing in a more useful way. Do you really think fixing bugs in design synopsis should be a higher priority than, say, web service consumer? This is where you think we should've been spending our time?

It's also worth noting that making even simple architectural changes is not without risk. You might say, "Oh, why don't you just make that buffer bigger?" But we're talking about rich text; the same buffer is used everywhere, and you can bet some places won't correctly handle the case of a bigger buffer. So there's a lot of work involved to make sure everybody's code is happy with the change.

But that feature has some limitations, one of which means it has been hidden when the default browser is not IE.

Again, all features have limitations. I'm well aware that now, well over 50% of the readers of this blog use the Firefox browser. At the time this feature was introduced, Firefox didn't even exist and IE was the browser that everyone (95%+) used, with no sign that this would ever change. In terms of "big product" release cycles, Firefox has taken off extremely recently. I personally am making sure that the feature is browser-agnostic in version 8.0.

Question: how is someone supposed to know that you would rather they use Transformer instead of Design Synopsis?

This shows why it's important to read my blog. :-)

I'm looking at the Designer 8.0 help document titled "Design synopsis", and I see it mentions the DXL Transformer and links to it. I'm not sure when that was added, but I don't think it's new in 8.0 because I don't remember seeing it while I was personally reviewing every Designer help document that changed for 8.0.

Incidentally, if you see a help document that's wrong or missing important information, please click the feedback link at the bottom of the document and tell us what you think should be there. The documentation team does pay attention to this feedback -- this is what I do myself in most cases.

 Add a Comment
Subject:
   
Name:
Comment:  (No HTML - Links will be converted if prefixed http://)
 
Remember Me?     Cancel

Search this blog 

Disclaimer 

    About IBM Privacy Contact