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

Dan Higgins higgins at nceas.ucsb.edu
Tue Feb 21 16:34:01 PST 2006 

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
>
>


-- 
*******************************************************************
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
*******************************************************************

More information about the Kepler-dev mailing list