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

[Zhijie Guan]

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