Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[aperi-dev] Re: Online help and the new GUI


I am moving this very interesting discussion to aperi-dev. I doubt the color coded commentary will come through that remailer.

My comments:
Yes, I agree with Bill. Report 'designers' are much fewer and further between than report 'readers'. The big question here is how much of the schema to document for the benefit of report designers. The books that Bill indicates are the BIRT bibles, but they are commercial properties. I don't think you will find references to them on the Eclipse web page, so its probably a foul to reference them in the open source product documentation (true or false?). The online help that comes with the report designer should be the help for that perspective.

All that is a slightly different question than whether we should document the columns for any given report. Certainly for any given report the help for that report should indicate which columns are present and which can be filtered. For the reports we provide there should be some documentation. Obviously, for user developed ad hoc reports its up to report developer. How does an ad hoc report developer add help for their report?


Dave Wolfe/Portland/IBM (dwolfe@xxxxxxxxxx) TL: 775-3376 Office: 503-578-3376 Personal: 503-329-3960

GUI Technical Lead, Aperi Open Source Storage Management http://www.eclipse.org/aperi http://www.ibm.com

If all of your problems look like nails you should invest in a good hammer - Unknown


Bill Warren/San Jose/IBM

01/17/2007 07:02 PM

To
Chris King/Chicago/IBM
cc
Dave Wolfe/Portland/IBM@IBMUS, Eric N Azares/Raleigh/IBM, Ophelia Yip/San Jose/IBM
Subject
Re: Online help and the new GUILink




Chris,

As a point of discussion, I think the users in the two reporting perspectives are going to "wearing very different hats," and have very different feelings about their help needs  --
  • For the Designer perspective:
    • The user would not normally be generating and viewing report results, of our Aperi standard reports.  They may be looking at the BIRT implementation of a report.  They will have a, more or less, "programmer" attitude  --  looking at the coding of the _javascript_ expressions, and such Yes, 'report designer' are few and far between and they are pretty specialized folk.
    • The Aperi data columns they are going to want explained will be those that appear in our BIRT "data sets," which will generally be a superset of those that appear in our reports.  The user will also be looking at the SQL queries we are using, and will want access to the underlying database schema column descriptions, including descriptions of the new view DB objects that Prasenjit will be delivering.
    I haven't done much digging, but, so far, I don't have a good feeling about ways to provide such information interactively while the Designer user is looking at a "data set" definition
    • For our Viewer perspective:
      • For the five reports we deliver in the 0.3 release, we should be able to use the content of the legacy help, as you describe
      • I want to make sure it is clear that, in the Viewer perspective, there is no BIRT-based UI implementation, and hence no BIRT-provided help, of any kind.  The Viewer uses the BIRT APIs to generate the HTML.  The Viewer then feeds that HTML directly to a standard Eclipse SWT browser widget
      These comments are just to provide some more background.  Another source of background info, that may be of some value, is a couple of books that have recently been published on BIRT.  We will, no doubt, be referring Designer users to these books as a base for their learning about the Designer  --

      • BIRT: A Field Guide to Reporting, whose info can be seen at these two places:
      • Field Guide to BIRT, Volume II: Understanding and Extending the BIRT Framework


      These books can be found by doing a search on "BIRT" at Barnes & Noble or Amazon.

      Bill

      Aperi Open Source Development
      IBM Tivoli, San Jose, CA    (408)284-5199 (t/l 953)



      Ophelia Yip/San Jose/IBM

      01/17/2007 06:35 PM

      To
      Chris King/Chicago/IBM
      cc
      Bill Warren/San Jose/IBM@IBMUS, Dave Wolfe/Portland/IBM@IBMUS
      Subject
      Re: Online help and the new GUILink




       Hi Chris,

      The summary you provided below was good.  I will provide my two cents in blue text below.  

      Best Regards,

      Ophelia Yip
      Phone:  (408)284-5226, T/L: 953-5226
      Aperi Development
      IBM Tivoli Storage Business Unit, San Jose, CA



      Chris King/Chicago/IBM

      01/17/2007 12:56 PM

      To
      Dave Wolfe/Portland/IBM@IBMUS, Ophelia Yip/San Jose/IBM@IBMUS, Bill Warren/San Jose/IBM@IBMUS
      cc
      Subject
      Online help and the new GUI




      Dave, Ophelia, Bill,

      I just want to get some thoughts down while the GUI demo meeting is still fresh in my mind. I might be wrong in my understanding of some of the components for 0.3, so please feel free to correct me. Once I get further along with the plan for the 0.3 help and documentation, I will post to aperi-dev for any further feedback.

      Documentation
      --------------------
      I think we need some type of document that provides an overview of how to use the RCP framework and BIRT report designer. We can either have a document separate from what we already have for Aperi, or integrate this information into the existing user's guide or install instructions. What are your thoughts about having such a document?

      What to do: create a new document that describes the new framework or add to one of the existing Aperi documents.

      Maybe we can provide a high level summary of what changes have been made to the Aperi GUI in the form of a release note and this summary can include:
      -   The entire legacy GUI is now encapsulated in RCP framework, etc and it's major differences, i.e. the bullets you listed below
      -   The Report Viewer and Report Designer are available and highlight on its capabilities.

      Online Help
      --------------------
      RCP Framework
      It doesn't appear that the RCP framework requires an extensive online help system at this point (or maybe not a separate online help system at all). The biggest visible differences I see at this point between the GUI of the legacy product and the product as it appears in the RCP framework are:
      • a new login screen
      Regarding Help info for the new Login Dialog, I am leaning towards adding a way to display Help from within the dialog such as adding a "Help" button or "?" icon on the left-hand corner and provide the same information in the User's Guide.   The problem with having it in the JavaHelp system is the user cannot really access the JavaHelp until after they are logged in.  
      Major changes of the login are:  
              - it now stores past connection info,  
              - allows user to delete invalid connection
              - has a separate field for the port number.  
      • the New Connection menu item has moved in the File menu
      To keep the Help consistent, I can move the New Connection back to where it used to be.  Otherwise, we also need to modify the current Help to say that New Connection resides within the File menu in the RCP gui instead of the Connection menu
      • the Look and Feel option has been removed from the Preferences menu
      Need to modify the current Help to address that the Look and Feel only applies for the legacy GUI
      • the fact the RCP framework exists
      Not sure if we need to mention this in the JavaHelp if we already stated it in the release note but maybe info about how to switch from the Classic GUI perspective to the Report perspective will be helpful.
      • "Print" has been removed from both the Menu and the Toolbar        
      • "Select Chart Engine" under Preferences has been removed

      What to do: I think for the 0.3 release of the product we can document these differences in the existing legacy JavaHelp system. Do either of you see a problem with documenting the RCP framework in the existing JavaHelp system? Then when it comes time to move from JavaHelp to an Eclipse-based system, we can migrate all the help at once without worrying about juggling help systems in different formats.


      BIRT Reports component
      While the actual BIRT designer has it's own Eclipse-based help, the Aperi reports that users will be able to generate within it are not included in that help. While those reports are documented in the legacy JavaHelp system, it makes sense to also document those reports using the same Eclipse help engine as used by BIRT.

      What to do: Create an eclipse-based help system (or add to BIRT's existing help) that describes the Aperi reports that appear in the BIRT report component.. As an alternative, we can either document these reports within a standard HTML/text file, or refer people to the existing JavaHelp system.

      I incline to the approach of adding to BIRT's existing help if possible and if this can be made happen within the current scheduled timeframe.   I believe it'll be easier for the user to look up information with a one-stop approach.

      _________________

      Chris King
      IBM Information Development - TPC, Aperi
      512.687.5166 / Tie line: 273.5547
      chriskng@xxxxxxxxxx
      TPC InfoCenter: http://publib.boulder.ibm.com/infocenter/tivihelp/v4r1/index.jsp
      TPC website: http://www-03.ibm.com/servers/storage/software/center/index.html
      Aperi: http://www.eclipse.org/aperi/index.php




Back to the top