[kepler-dev] Documentation of demo workflows for Kepler Alpha 9 release
Zhijie Guan
guan at sdsc.edu
Tue Feb 21 14:18:29 PST 2006
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
>>
>>
>
>
More information about the Kepler-dev
mailing list