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

[Christopher Brooks]

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
>