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

[Chad Berkley]

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