[kepler-dev] Documentation of demo workflows for Kepler Alpha 9 release

[Laura L. Downey]

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" <guan at sdsc.edu>
>>> To: <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