[kepler-dev] Getting Started Feedback
Glen Jarvis
glen at glenjarvis.com
Wed May 2 23:03:12 PDT 2007
Kirsten,
Here is the beginning of my feedback. I'm sorry I didn't get it to
you last week. I never did get on that plane, and as a consequence my
planning for the next two weeks is totally upset.
However, I spent a few hours tonight working on making my notes
make sense. I am only on page 6 of 43 (roughly 14% finished). Please
remember that I *really* found the guide helpful on my first pass and
that these notes are extremely nit-picky. However, I've always
believed in digging into the details to make something even better.
I'll pick up where I left next Monday or Tuesday. I'll also send you
my cryptic/quick notes in a private email in case they are helpful.
All comments below have been verified with nightly build for
2-May: kepler20070502.
Suggestion #01
Page #01
Old paragraph:
> 3. Starting Kepler.........................................7 3.1.1.
> Windows and Macintosh Platforms.....................7 3.1.2. Linux
> Platform......................................7 4. Basic Components
> in Kepler..............................7
Comments:
For parallelism, it seems we are missing a 3.1 and jump straight
into 3.1.1 and 3.1.2.
Possible Suggestion:
I'm not sure this needs fixed. This structure seems odd to me, and
it contradicts the other structures (like in 6) but if fixing it means
writing sections that don't make sense, then we'd be forcing a square
peg into a round hole and it's better to leave it as it is. Whatever
needs done, I wanted to point it out.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #02
Page #02
Old paragraph:
> 8. Appendix.........................................42 8.1. Ptolemy
> II The Foundation of Kepler...............42
> 8.2................Error! Bookmark not defined. 8.3. Actor
> Reference..................43 .
Comments:
This is a simple bookmark error that will be fixed with a rebuild
of the TOC.
Possible Suggestion:
Rebuild TOC.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #03
Page #03
Old paragraph:
> Kepler users with little background in computer science can create
> workflows with standard components, or modify existing workflows to
> suit their needs. Quantitative analysts can use the visual interface
> to create and share R and other statistical analyses. Even advanced
> users will find that Kepler offers many advantages, particularly
> when it comes to presenting complex programs and analyses in a
> comprehensible and easily shared way.
Comments:
Although a great deal of readers of this document will understand
what the language 'R' is, some will not. It is suggested to add one or
two sentences to help explain and let the reader know that it is not
necessary to know the 'R' language to successfully use Kepler.
Possible Suggestion:
> Kepler users with little background in computer science can create
> workflows with standard components, or modify existing workflows to
> suit their needs. Quantitative analysts can use the visual interface
> to create and share R and other statistical analyses. R is a language
> developed at Bell Laboratories that is used for statistical
> computing and graphics. It is not necessary to know the R language
> to use Kepler.
> Even advanced users will find that Kepler offers many advantages,
> particularly when it comes to presenting complex programs and
> analyses in a comprehensible and easily shared way.
Note#1: My comments on the R-language are not original thought. This may
or may not need to be cited. My source information came from
http://www.r-project.org/about.html in the first paragraph.
Note#2: We do say on page (see below) that it is not needed to know
the 'R' language to successfully use Kepler. This is not
said, however,
when the 'R' language was first introduced in the manual.
Could we keep
this phrasing in both places, or move the phrasing up to the first
introduction to 'R'?
From page 4:
> Kepler users need not know how to program in R in order to take
> advantage of its powerful analytical features; pre-programmed Kepler
> components can simply be dragged into a visually represented workflow.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #04
Page #04-05
Old paragraph:
> Connected actors (and a few other components that well discuss in
> later sections) form a workflow, allowing scientists to inspect and
> display data on the fly as it is computed, make parameter changes as
> necessary, and re-run and reproduce experimental results.1 [This 1
> is a superscript for a footnote.]
Comments:
This footnote is not at the bottom of the page, but instead is at
the end of the section on page 5. This was confusing to me since I had
to go looking for the footnote. There may be stylistic reasons for the
footnote to follow the end of the section. Personally, I believe the
bottom of the page is best.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #05
Page #04
Old paragraph:
> Workflows also provide: * documentation of all aspects of an
> analysis; * visual representation of analytical steps; ...
Comments:
This may only be a style issue. The extra carriage return after
the "Workflows also provide.." seems to disconnect the bullet points
that finish the sentence. That is, since the bullets are of the same
sentence that begins "Workflows also..," then there should be no extra
carriage return.
Possible Suggestion:
Remove the extra carriage return after the word "provide..."
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #06
Page #06
Old paragraph:
> *NOTE: Java 1.4 or higher is required and can be obtained from
> Suns Java website at: http://java.sun.com/j2se/downloads/ or from
> your system administrator. Some Kepler installations include Java
> 1.4 and others do not. Check to see if your version of Kepler
> includes Java before downloading it from
> http://kepler-project.org/Wiki.jsp?page=Downloads.
Comments:
This note is confusing for the first-time reader. It is helpful in
that it states that "[s]ome Kepler installations include Java ... and
others do not," but the suggestion to "check to see if your version of
Kepler includes Java before downloading it..." does not show how until
the link is followed. The link
"http://kepler-project.org/Wiki.jsp?page=Downloads" is not recognized
as a hyperlink in the document. And, the page that is loaded has so
many options and so much information, it is overwhelming to a
first-time user. Stylistically, this note could be a comment box with
a warning graphic like the wingding "bomb" to catch the reader's
attention immediately. The asterisk before the NOTE also does not fit
the style of the rest of the document.
Possible Suggestion:
> NOTE: Java 1.4 or higher is required for Kepler to work. Some
> Kepler installations include Java 1.4 or higher and others do not.
> The instructions below will help you determine if you need the Kepler
> installation that includes Java or not. Skip to the section that relates
> to the Operating System where you are installing Kepler.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #07
Page #06
Old paragraph:
> Two versions of Kepler are available for installation on a
> Windows machine: one with Java; and one without Java. If you do not
> have Java 1.4 (or higher) installed, be sure to download the Kepler
> package that includes Java or download and install Java from Suns
> website. Follow these steps to download and install Kepler for
> Windows:
Comments:
The reader may not know if they have Java 1.4 on Windows or not. I
suggest adding the phrase "or if you are uncertain if Java 1.4 or
higher is installed," as shown below.
Possible Suggestion:
> Two versions of Kepler are available for installation on a
> Windows machine: one with Java; and one without Java. If you do not
> have Java 1.4 (or higher) installed, or if you are uncertain
> if Java 1.4 or higher is installed, be sure to download the Kepler
> package that includes Java or download and install Java from Suns
> website. Follow these steps to download and install Kepler for
> Windows:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #08
Page #06
Old paragraph:
> 1. Click the following link:
> http://kepler-project.org/Wiki.jsp?page=Downloads and select the
> desired Windows version (with or without Java).
Comments:
The URL listed does load the download page. Clicking on this link,
however, does not. Instead the page:
http://kepler-project.org/Wiki.jsp?page=Downloads%20 is loaded. Note
the %20 (that is the hexadecimal code for an embedded 'space') that
has been added to the end. Simply backspacing over this space within
the link should correct the problem.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #09
Page #06
Old paragraph:
> [Section 2.3]
> 1 Click the following link:
> http://kepler-project.org/Wiki.jsp?page=Downloads and select the Mac
> install file. Save the zipped install file to your computer....
Comments:
This is a similar problem as suggestion #08. The URL listed does
load the download page. Clicking on this link, however, does not.
Instead the page: http://kepler-project.org/Wiki.jsp?page=Downloads%20
is loaded. Note the %20 (that is the hexadecimal code for an embedded
'space') that has been added to the end. Simply backspacing over this
space within the link should correct the problem.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Suggestion #10
Page #06
Figure 2
Comments:
The icon in Figure 2 is no longer what is placed on the desktop
when it is installed. Also the icon is cut from a blue desktop which
would be confusing to users who do not have that blue desktop. I had
intended to download the Beta, take a screenshot of the icon after
installation, and then editing the graphic so that it has a
transparent background. However, for time constraints, may I send this
to you next?
Warmest Regards,
Glen Jarvis
--
913-486-8775
glen at glenjarvis.com
http://www.glenjarvis.com
"You must be the change you wish to see in the world." -M. Gandhi
More information about the Kepler-dev
mailing list