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

Matthew Brooke brooke at nceas.ucsb.edu
Tue Feb 21 15:57:02 PST 2006


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