[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [aperi-dev] Re: Online help and the new GUI
- From: Ted Slupesky <slupesky@xxxxxxxxxx>
- Date: Thu, 18 Jan 2007 13:05:03 -0800
- Delivered-to: firstname.lastname@example.org
Let me see if I'm understanding this
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,
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)
Sent by: aperi-dev-bounces@xxxxxxxxxxx
01/18/2007 08:16 AM
Please respond to
Aperi Development <aperi-dev@xxxxxxxxxxx>
|[aperi-dev] Re: Online help and the
I am moving this very interesting discussion to aperi-dev. I doubt the
color coded commentary will come through that remailer.
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?
TL: 775-3376 Office: 503-578-3376 Personal: 503-329-3960
GUI Technical Lead, Aperi Open Source Storage Management
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
|Dave Wolfe/Portland/IBM@IBMUS, Eric
N Azares/Raleigh/IBM, Ophelia Yip/San Jose/IBM
|Re: Online help and the new GUILink|
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:
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
- 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
'report designer' are few and far between and they are pretty specialized
- 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
- For our Viewer perspective:
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
- For the five reports we deliver in the
0.3 release, we should be able to use the content of the legacy help, as
- 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
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.
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
|Bill Warren/San Jose/IBM@IBMUS, Dave
|Re: Online help and the new GUILink|
The summary you provided below was good. I will provide my two cents
Phone: (408)284-5226, T/L: 953-5226
IBM Tivoli Storage Business Unit, San Jose, CA
01/17/2007 12:56 PM
Ophelia Yip/San Jose/IBM@IBMUS, Bill Warren/San Jose/IBM@IBMUS
|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.
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.
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:
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
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.
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 New Connection menu item has moved
in the File menu
to modify the current Help to address that the Look and Feel only applies
for the legacy GUI
- the Look and Feel option has been removed
from the Preferences menu
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.
- the fact the RCP framework exists
- "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.
IBM Information Development - TPC, Aperi
512.687.5166 / Tie line: 273.5547
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-dev mailing list