Re: [aperi-dev] Re: Online help and the new GUI

[Ted Slupesky <slupesky@xxxxxxxxxx>]

Let me see if I'm understanding this
right:

1 - We shouldn't write generic BIRT
documentation as part of Aperi, as it's already covered elsewhere. This
would apply to, say, generic aspects of interacting with the report designer.
2 - We should write documentation about
how specifically to use BIRT with Aperi (perhaps, how to configure the
data source for the Aperi repository, how to switch to the various perspectives,
etc.).
3 - Any reports delivered as part of
Aperi should have help equivalent at least to the existing online help
we have for our current reports.
4 - The data model itself needs documentation
like a programmer's manual, so that report designers can figure out what
queries to write for their reports.

--
Ted Slupesky | Eclipse Aperi Project Lead | IBM: 349-5413 | External: (503)
820-3853

Dave Wolfe/Portland/IBM@IBMUS
Sent by: aperi-dev-bounces@xxxxxxxxxxx

01/18/2007 08:16 AM

Please respond to
Aperi Development <aperi-dev@xxxxxxxxxxx>

To	aperi-dev@xxxxxxxxxxx
cc
Subject	[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
    
    
    _______________________________________________
    aperi-dev mailing list
    aperi-dev@xxxxxxxxxxx
    https://dev.eclipse.org/mailman/listinfo/aperi-dev