[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 we’ll 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  
> Sun’s 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 Sun’s  
> 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 Sun’s  
> 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