[kepler-dev] Documentation of demo workflows for Kepler Alpha 9 release
Dan Higgins
higgins at nceas.ucsb.edu
Tue Feb 21 15:38:47 PST 2006
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" <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
>
>
>
--
*******************************************************************
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/20060221/b7790cdc/attachment-0001.htm
More information about the Kepler-dev
mailing list