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

[Dan Higgins]

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mercury.nceas.ucsb.edu/kepler/pipermail/kepler-dev/attachments/20060221/ea9034fc/attachment.html>