[kepler-dev] Documentation of demo workflows for Kepler Alpha 9 release
Laura L. Downey
ldowney at lternet.edu
Wed Feb 22 08:32:11 PST 2006
Oh I totally agree Dan that full workflow documentation should be available
from the workflow - whether from some "documentation" actor or some menu
item. My first thought is that since actor documentation is available from
the menu, that workflow documentation should be available from the menu
also. But those are details that can be hashed out later. I would think
most people agree that workflow documentation is important and should be
available somehow from the workflow.
Laura L. Downey
Senior Usability Engineer
LTER Network Office
Department of Biology, MSC03 2020
1 University of New Mexico
Albuquerque, NM 87131-0001
505.277.3157 office
505.610.9657 mobile
505.277-2541 fax
ldowney at lternet.edu
_____
From: Dan Higgins [mailto:higgins at nceas.ucsb.edu]
Sent: Tuesday, February 21, 2006 4:39 PM
To: Laura L. Downey
Cc: 'Zhijie Guan'; Kepler-dev at ecoinformatics.org
Subject: Re: [kepler-dev] Documentation of demo workflows for Kepler Alpha 9
release
Hi All,
I really do think full documentation should be available from the
workflow itself. It need not all appear all the time. Edward had an example
where more information could be displayed as desired. Also, see
workflows/eco/compositeBiodiversityExample.xml which has a
'DocumentationAttribute' ("Double click to see documentation"). In this
example an HTML file with the equations can be displayed directly from the
workflow.
Dan
----
Laura L. Downey wrote:
I'm coming in a little late to this. I agree Zhijie that we don't want to
put full documentation in as notes or annotations on the workflow itself as
displayed on the canvas, but only essential or summary type information.
And I also agree that it would be nice to have a workflow documentation
template too. I had put a very simple thing together for the samples we
want to document for Release 1.0 and it looks like this, I can't display it
in table format since this is plain text email:
Sample Workflow - name of workflow
Name
GARP Workflow
Filename
/kepler/workflows/eco/???????.xml
Detailed Description
Paragraph of stuff with pertinent details that give more information than
the brief description, describes the general inputs and pieces and what
output can be expected etc.
Assumptions
Describe any assumptions the model is based on
Director
Which director is used and why if any explanation is needed
Data
List of data files used
Actors
List of actors used in the workflow
Parameters
List of parameters used in the workflow, may include workflow, director,
actor or port parameters
<insert graphic here of workflow as displayed in Kepler - should we show
before or after execution?>
Provide here any discussion about substituting different data or different
processing components and any discussion about assumptions if needed, and/or
about setting or configuring any parameters etc.
Laura L. Downey
Senior Usability Engineer
LTER Network Office
Department of Biology, MSC03 2020
1 University of New Mexico
Albuquerque, NM 87131-0001
505.277.3157 office
505.610.9657 mobile
505.277-2541 fax
ldowney at lternet.edu
-----Original Message-----
From: kepler-dev-bounces at ecoinformatics.org
[mailto:kepler-dev-bounces at ecoinformatics.org] On Behalf Of Zhijie Guan
Sent: Tuesday, February 21, 2006 3:18 PM
To: Dan Higgins
Cc: Kepler-dev at ecoinformatics.org
Subject: Re: [kepler-dev] Documentation of demo workflows for Kepler Alpha 9
release
Hi, Dan,
I like the idea of putting some infomation in the workflow as annotations.
I saw some of our workflows have already used this way to convey
information to the user. I would use this approach in my workflows as
well. But including ALL the workflow documentation in workflows seems to
be a problematic approach -- it may mess the appearance of the workflow
model and distract users from the "flow-control" idea which is carried by
the model.
So for the whole workflow documentation framework, I prefer an approach
similar to the actor documentation framework presented by Edward on the
Kepler meeting. I think the whole Kepler group still needs a lot of
discussion on how to document workflows, what should be recorded in
documentation, and in what format it should be included. I would like to
follow any format (plain text, html, xml, or pdf) once our group get an
agreement on this issue.
I agree that getting all the workflow documentations done before Alpha 9
is kind of mission impossible. And I am not quite clear when we planned to
setup the documentation framework for workflows. Actually I realized that
maybe I used the wrong words "workflow documentation" in my initial email.
This made me start a hot discussion of workflow documentations and jump
into it directly (which I don't want), though I think this discussion will
benefit our whole group, thus we should start it as early as possible. B->
My initial motivation of recording info for workflows is for workflow
testing. As you can see in my proposed format, most of the info recorded
is for testing workflows. So I should call it "testing notes" instead of
workflow documentation. It's a way to ease my life since my task for Alpha
9 release is to make sure every workflow included can be run by the user.
If any workflow cannot be run, the user should at least have the rights to
know how to make it run.
I started to test those workflows in $KEPLER/workflows since last week.
The current situation is about 90% of the workflows I tested cannot be run
on my poor Linux box. Some workflows require specific softwares installed
in the system; some of them require users setting parameters; some of them
cannot even be loaded by Vergil. I think a piece of note on how to run
those workflows would be helpful for me to test the workflows manually.
Thanks!
Zhijie
On Tue, 21 Feb 2006, Dan Higgins wrote:
Hi Zhijie
Your suggested set of information that should be in workflow documentation
looks good. However, I have some thoughts about just where it should
appear.
First, it seems to me that the best place for most workflow documentation
is
_in the workflow_ - i.e. as an annotation. This puts the documentation in
the
Moml so it cannot be separated from the workflow. Every thing can be seen
at
once. A separate text document would be hard to interpret without seeing
the
workflow.
Also, if we have a seperate document, I think html or pdf format is more
appropriate since images from the workflow are almost essential to explain
some details.
It was also my understanding that actual workflow and actor documentation
will appear aftert the Alpha9 release, and only the documentation
framework
is planned for Alpha9. Is that correct? And since the Alpha9 is scheduled
in
a week, completion of documentation by that time seems unlikely ;-)
Dan
Zhijie Guan wrote:
Hi, Christopher,
Thanks for sharing the Ptolemy experience with us. It is really important
to have a systematic way for workflow documentations. The way described
in
my email is only a temporary proposal to record related info about
workflows. I think we still need more discussion on the approach for
Kepler workflow documentations in the near future. I'd like to use the
proposed way to collect information for other developers (like myself) to
test existing workflows, and for the end users to understand how to run
workflows.
BTW, would you please give me some idea about automatically testing
models
in Ptolemy? I'd like to integrate the workflow testing in Kepler nightly
build. But I don't know how to simulate the user input in the automatic
testing.
Enjoy your vacation!
Zhijie
On Sat, 18 Feb 2006, Christopher Brooks wrote:
Hi Zhijie,
.doc is probably not the right extension since under Windows .doc means
Microsoft Word.
Perhaps it would be better to put this information in a .htm file
with <h2>...</h2> sections for each of the questions?
That way, anyone can easily edit the file by double clicking on it.
Perhaps the file should be called ModelNameDoc.htm?
In Ptolemy II, we found it very helpful to follow naming conventions
for files. So, a demo called "Spectrum" is a .xml file called
demo/Spectrum/Spectrum.xml. For applets, the applet would
be called demo/Spectrum/Spectrum.htm. Perhaps the
additional documentation would be in a file called
demo/Spectrum/SpectrumDoc.htm?
We required demo names to follow the Java class naming
conventions (alphanumeric only) so that we can easily generate
code for demos.
The advantage of a strict naming convention is that it makes it
easy to refer to other demos without struggling with the contents
of each directory.
_Christopher
----- Original Message ----- From: "Zhijie Guan" <mailto:guan at sdsc.edu>
<guan at sdsc.edu>
To: <mailto:Kepler-dev at ecoinformatics.org> <Kepler-dev at ecoinformatics.org>
Sent: Friday, February 17, 2006 5:39 PM
Subject: [kepler-dev] Documentation of demo workflows for Kepler Alpha 9
release
Dear workflow authors,
To make sure all the workflows included in Kepler Alpha 9 release can
be
run successfully, Ilkay and I need your help to prepare a
documentation
for each workflow on how to run them.
The documentations should be checked in into the CVS repository along
with
the workflows. We hope each workflow could have its own doc just like
each
actor has its own doc. Since currently we do not have common-agreed
framework about how to document workflows, I suggest we use plain text
files to record workflow related info. The document should be stored
in
the same directory with the workflow, have the same name with the
workflow, but with a file extension ".doc". We can easily transform
the
plain text file to the doc format if we have a doc framework for
workflows
in the future.
The doc for a workflow should answer the following questions:
1. What's the goal/purpose of this workflow?
2. Who are the authors?
3. How to run this workflow?
3.1 What OS can this workflow be run on? (Windows/Linux/Unix/Mac)
3.2 What additional software are needed?
3.3 Does the user need to do any settings? (like the path of the
temporary
file, the number of iteration times, etc)
3.4 Does the user need any account/password?
3.5 What database/web services/web-based applications are used in the
workflow? Are they available usually?
3.6 Is there any other things that the user need to do to run this
workflow?
4. What does the user expect to see as the result of the workflow?
So here I suggest we write the doc according to the following format
(shown as a doc for workflow "RecIDCM3.xml").
RecIDCM3.doc
================================================
Goal: Simulate RecIDCM3 algorithm with the CORBA services provided by
the
CIPRES SDK.
Author(s): Zhijie Guan, Terri Liebowitz, Alex Borchers (contact:
guan at sdsc.edu)
Compatible OS:
Mac (Yes. tested)
Windows (No. CIPRES SDK is not compatible with windows)
Linux/Unix (No. CIPRES SDK is not compatible with Linux/Unix)
Additional Software: CIPRES SDK (which is not included in Kepler)
should
be installed in $KEPLER/lib/jar/cipres
Setting(s): The user needs to choose the input NEXUS file from the
FileChooser dialog
Account/Password: N.A.
Database: N.A.
Web Services: N.A.
Web-based Applications: N.A.
Comments: N.A.
Results: The user should see two phylogenetic trees shown in two ATV
windows. One tree comes from the input NEXUS file. The other is the
optimal tree improved by RecIDCM3 algorithm.
===================================================
Any suggestions/comments/opinions are highly appreciated!
Regards,
Zhijie Guan
_______________________________________________
Kepler-dev mailing list
Kepler-dev at ecoinformatics.org
http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
_______________________________________________
Kepler-dev mailing list
Kepler-dev at ecoinformatics.org
http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
_______________________________________________
Kepler-dev mailing list
Kepler-dev at ecoinformatics.org
http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
--
*******************************************************************
Dan Higgins higgins at nceas.ucsb.edu
http://www.nceas.ucsb.edu/ Ph: 805-893-5127
National Center for Ecological Analysis and Synthesis (NCEAS) Marine Science
Building - Room 3405
Santa Barbara, CA 93195
*******************************************************************
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/kepler-dev/attachments/20060222/b1bf5a8b/attachment-0001.htm
More information about the Kepler-dev
mailing list