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

[Zhijie Guan]

Agree. More discussion on the content and format of the workflow 
documentation are needed.

Zhijie

On Tue, 21 Feb 2006, Chad Berkley wrote:

> I agree with Christopher here.  I don't think we should mix file extensions. 
> It's confusing later.
>
> chad
>
> 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
>