[kepler-dev] Documentation of demo workflows for Kepler Alpha 9 release
Matthew Brooke
brooke at nceas.ucsb.edu
Tue Feb 21 17:01:45 PST 2006
Dan -
At the meeting, we talked about putting Kepler documentation directly in
the moml, IIRC, but at the time, i didn't really know enough about the
documentation to comment. I still don't, but am throwing caution to the
wind... ;-)
m
Dan Higgins wrote:
> Matthew,
> Some good points.
> I have really been more concerned with being able to link the
> documentation to the workflow so a user can get to it from the workflow.
> I thought that Edward's new documentation capabilities for PT handled
> this (somehow) and took care of some of the technical details you
> mentioned (i.e. allowing easy editing for maintainance, etc.), but I am
> unsure of just how his new stuff works.
>
> Dan
>
> ---
>
> Matthew Brooke wrote:
>
>>
>> A question regarding implementation of documentation:
>>
>> Why are we not seriously considered keeping the documentation separate
>> from the moml? Java has a built-in localization framework,
>> specifically intended for text that will be seen by users, which may
>> need to be translated into other languages and/or edited/corrected
>> frequently.
>>
>> This would provide 3 major benefits:
>>
>> 1) Creating, say, a Spanish version of Kepler would mean only changing
>> out the English resource-bundle files for Spanish ones, instead of
>> having to edit and track 2 versions of each moml file
>>
>> 2) keeping the documentation out of the moml files would make it much
>> easier to maintain, especially by people who are non-technical and
>> don't read "XMLish"
>>
>> 3) We wouldn't have to mess with the MOML schema, which doesn't
>> currently allow for adding documentation, if my understanding is correct.
>>
>> From a high level design/architecture point-of-view, the moml just
>> seems like the wrong place for this stuff - or am i missing something
>> obvious?
>>
>> m
>>
>>
>>
>> Dan Higgins wrote:
>>
>>> 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
>>> *******************************************************************
>>>
>>>
>>> ------------------------------------------------------------------------
>>>
>>> _______________________________________________
>>> Kepler-dev mailing list
>>> Kepler-dev at ecoinformatics.org
>>> http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
>>
>>
>
>
--
---------------------------------------------
Matthew Brooke, Ph.D.
Marine Sciences Research Building, Room #3407
University of California
Santa Barbara, CA 93106-6150
ph: (805) 893-7108 fx: 805-893-8062
brooke at nceas.ucsb.edu
---------------------------------------------
More information about the Kepler-dev
mailing list