Documentation Action Items

Getting Started Guide

• Remove Appendix 8.2 “Technical Overview of Kepler”
• Change Figure 1 to an R workflow instead of addition workflow/move figure 1 up.
• Redo Figure 2 with Lotka Volterra Workflow. Move figure 2 up.
• Move sections 3 & 4 (installing and starting kepler) after section 1.
• Redo screenshots with colors and new workflows (for graphics folks; do basic images)
• Remove “Atomic” distinction (Actors and Composite Actors)
• Remove references to “ontologies”; use “categorization” instead.*Clarify Nested Composite Actors/Workflows (add line diagram and explanatory paragraph to “1.2. What are Scientific Workflows” section. Note: Introduce early and move figure lower in doc
• Add paragraph about who Kepler is for/advantages for different types of users (sharing workflows/advanced users; “quantitative analyst” background (run and param; follow logic of workflow).
• Clarify Data Actor (“widget that supplies the data/not the data”)

• Add paragraph with references to other systems (Stella; Simulink (kepler like), R, Matlab, Excel, SAS)
• Feedback due by end of next week (Sept 15)
• update note that most workflows require a network connection when running Kepler. Access resources that are on the network.
• Create a stand-alone glossary (actor, relation, token, float, double, data type, port, channel, relations, components, etc)

• Update section 5.3 Director and Actor Icons with most recent icon categories. (design docs on wiki have out-of-date icons; 3 all-the-actors actor in workflows directory also not up-to-date; photoshop doc Matt made?)
• create a list of all changes to screenshots and work with NCEAS/UCSB people on creating screenshots.

• Make the listservs searchable

• Adding appendix about R (also looping and how to choose a director (DAN), creating composite actors, how to import non-EML data tab and comma delimited) & make footnote describing ALSO: R workflows have to be present in Kepler release.

Actor Documentation

• Create guidelines for how to write documentation for actors (Actor documentation guidlines)and Sam to place on Wiki COMPLETE
• Must note dependencies in the actor docsCOMPLETE
• R actors need R installedCOMPLETE
• GRASS actors need GRASS installedCOMPLETE
• Matlab needs Matlab installed COMPLETE
• command line actor depends on system-specific executables and is operating-system specific.COMPLETE
• Web Service actor: Update copy to reflect that the actor only works for a subset of WSDL constructs. Only ones that use base types for parameters or arrays of base types. “Intended to work on any web service with certain limitations, in particular related to the types of parameters that are used as input and output to Web Service.” Define “Web Service” in first paragraph e.g., “which is a… computer program that runs on a remote host using a standardized protocol.” COMPLETE
• Random Normal actor: this uses R norm and hist function—add note “For a full detailed desc. of how this actor works, look at R norm docs”COMPLETE
• AddGrids actor: Revise to say that actor takes “two or more geospatial images”/less jargon-y. Update desc. about file formats—it is not generically true that all actors use ESRI ASCII file format (e.g., not true for Interpolate actor)COMPLETE
• EOL actors (“Encyclopedia of Life”) are not active any more and will likely be removed.
• Boolean Multiplexor actor: Revise to include context (used as a control flow actor/for branching) Suggested first sentence: “The Boolean Multiplexor uses a Boolean value to determine which of two input values to output.” COMPLETE
• Boolean Switch actor. Needs more context; only works under certain directors (SDF does not work; PN does work)COMPLETE
• Expression actor: Change to read “actor evaluates a specified expression”COMPLETE

• send email on VariableSetter(developer to look at and clarify how this actor works)
• send email to Efrat to document*TransitiveClosureDatabaseQuery COMPLETE
• send email to Christopher to review Image Contrast actor documentation to clarify COMPLETE
• send email to Jianting to generalize actor and redocument ENM PCP actor without reference to niche model (PCP==Parallel Coordinates Plot). COMPLETE
• Add "documentation" to testing spreadsheet to track doc status. (Matt and Sam)
• Update Ptolemy actor documentation for releases. Flag the change and update the Kepler docs appropriately.
• Incorporating documentation into application
• Strategy: Use the Actor right-click menu to update the individual documentation screens (i.e., update the actor's MOML files). Use HTML <p>, <i>, and <tt> tags to preserve formatting. Save the updated actor files as KAR file and then overwrite the existing files in the /Kepler/src/actors directory in CVS.
• In the current system, the application will display the Java doc, unless there is doc info in the corresponding MOML file, which will override the Java doc. The system also examines the class and displays that name. An example of an actor with a MOML doc is the Scatterplot actor.
• Documentation about ports and parameters should only be pasted into the actor if it differs from its base class. Will this work? Now that I'm writing this up, I'm a bit confused. We're updating the MOML file, right? Will the class MOML file overwrite a child's Java docs?

• clarify Interpolator actor
• Directors (SDF, PN, etc) Need more of a functional description.
• Look into using the first sentence of each actor description as a tooltip. May involve some rewriting.
• Fix "Save as KAR" option so that new doc files can be saved (Chad; Dan to look at quickly)
• Nandita's auto-actor-doc generating system is not currently working properly. Need a mechanism for generating a complete actor doc in useful formats (HTML, Text, PDF) so that the docs are easy to update and reference.
• look into the implications of using spaces in actor and parameter names. And then to decide on a convention.

• Decide which actors will be incorporated into the release (Ilkay, Matt, and Bertram)

• Make MOML files the place where actor and parameter names are edited so that these names can be updated when the Documentation screens are updated.

User Manual Outline

• Create a list of common problems encountered when building workflows and types of solutions This material will be incorporated into Section 5 “Building Workflows with Existing Actors” (developers make list).

• Create an R actor that takes CSV/tab delimited data files and parses them. This will be used when we talk about working with local data in Section 6 “Working with Datasets” (Dan)

• Update the Outline COMPLETE
• the Expression Actor is important and should be highlighted.
• Section 4
• Move section 4.5.4 & 4.5.5. down to section 5. (section 5.4)
• In section 4.4.2. Mention R actor as type of actor to customize
• Section 5
• Change this section title to “Building Workflows with Existing Actors”
• Add information about looping, expression actor, other common workflow problems and solutions based on the list of problems/solutions/techniques compiled by the developers.
• Remove all Build new actor docs and place in appendix, developer reference, or separate chapter.
• 5.4-5.4.6 Should go into a separate developers’ guide or an appendix. “Developing new actors with Java”
• Move 5.4.8 down to 5.8.
• 5.5 Call section “Documenting Workflows”
• 5.7 & 5.8 combine “Saving and Sharing Workflows”
• Save to Library (for self); Save as KAR (for someone else); Upload to the repository (for the public)
• NEW section 5.5.3 Need to add “semantically annotating actors”
• Remove 5.8.2. Creating Applets
• Section 6
• need to open with general intro to data types and incorporate spatial data/other data types in addition to local/remote distinction. Basic/new structure for chapter noted below. Note that you cannot open an Excel spreadsheet directly.
• 6.1. Start with introduction on Handling Data Intro: overview of different kinds of data/many kinds available/easy to access/etc
• 6.1.1. should be “Ecological Metadata Language”
• 6.1.2. ADN (geon uses) Metadata; Remove Darwin Core is not metadata (it is data format);
• Move 6.2 after 6.3/or interweave with 6.3. and 6.5.
• New Structure:
• A. Tabular (rows & columns)
• 1. Using local data (opening Comma, tab, text delimited file)
• 2. Opening local with EML
• 3. Finding and opening documented data (remote/EcoGrid)
• 4. Getting data external database
• 5. Other kinds of data (SRB, system specific actors)
• 6. Parsing more complex text data formats (recognition that are other formats; make suggestions for how to deal with them. General advice)
• B. Spatial (image handling, too)
• 7. Using local data
• 8. Opening local with EML
• 9. Finding and opening documented data (remote/EcoGrid)
• 10.Getting data external database
• 11.Other kinds of data (SRB, system specific actors)
• 12.What do with spatial data different from tabular data
• C. Other Data Types
• 1. Sequence Type (Gene & Protein sequences)

• Section 7
• Rename section 7 “Using Remote Computing Resources”
• 7.1. Using Web Services
• 7.2. Using Computational Grids (NIMROD, Globus, Griddles) (current 7.1. moved inside this section)
• Remove 7.4
• Section 8
• Add 8.1a Expression Actor (before R chapter)
• Add 8.3. MatLab subchapter
• 8.1.4. place the R GSG Appendix R material here.
• Add: 8.3. Image data (ways to manipulate images)-- ImageJ, Rescaling, clipping, color balance, alpha value out.
• Section 9:
• Rename section 9 “Domain Specific Example Workflows”
• Revise so that this section consists of an intro for each domain/then work through examples.