Science Environment for Ecological Knowledge
Ecoinformatics site parent site of Partnership for Biodiversity Informatics site parent site of SEEK - Home
Science Environment for Ecological Knowledge









 

 

 



Doc Writing

Difference between version 42 and version 30:

Line 7 was replaced by lines 7-8
- !Objective
+
+ !Objective:
Removed line 11
- __Wednesday pm__
Removed line 13
- __Thursday am__
Removed lines 15-16
- *discuss/define actor documentation user
- __Thursday pm__
Removed line 18
- *wrap up and action points
At line 27 added 3 lines.
+ __[Documentation Action Items]__\\
+ __[Documentation Meeting Notes]__\\
+
Removed lines 38-142
-
- __Action Items:__
-
- !Getting Started Guide
- __Kirsten__
- *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)
- __Samantha__
- *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.
-
- __Mark__
- *Make the listserv
-
- __Dan__
- *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.
-
- Notes from meeting
- *Started out as a 5 minute guide but has shifted to a more complete document that can be scaled back
- *Put some of the more detailed r expression actor documentation that Samantha wrote and Dan Higgins documentation on iteration and how to choose directors and creating composites and can be reviewed by Kirsten\\
- *use this meeting to review the guide section by section
- *provide kirsten with a written comments
- *Gap between this and building your own workflow
- *Clearly defining token; actor as vehicle
- *we need to clearly define that the actor is dynamic and the vehicle that transports the data; the data is a token. The actor is not the data. In Kepler you start with open the analysis data flows traditional analysis programs start with the data and view the data and move from that to the analysis. Metaphor source -- the fountain; sink -- the end point.
-
- !Actor Documentation
-
- Kirsten
- *Create guidelines for how to write documentation for actors and Sam to place on Wiki
- *Must note dependencies in the actor docs
- **R actors need R installed
- **GRASS actors need GRASS installed
- **Matlab needs Matlab installed; command line actor depends on system-specific executables and is operating-system specific.
- *''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.”
- *''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”
- *''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)
- *''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.”
- *Boolean Switch actor. Needs more context; only works under certain directors (SDF does not work; PN does work)
- *''Expression actor'': Change to read “actor evaluates a specified expression”
-
- Sam
- *send email on ''VariableSetter''(developer to look at and clarify how this actor works)
- *send email to Efrat to document*TransitiveClosureDatabaseQuery
- *send email to Christopher to review Image Contrast actor documentation to clarify
- *send email to Jianting to generalize actor and redocument ENM PCP actor without reference to niche model (PCP==Parallel Coordinates Plot).
-
- Dan
- *clarify Interpolator actor
- *Directors (SDF, PN, etc) Need more of a functional description.
-
- Notes from meeting
- *review the actor documentation and come to agreement.
- *entire component ontology completed -- ~20 not completed because of lack of developer documentation
- *60 remaining actors.
- *some of the actor documentation is out of the scope of SEEK.
- *xml transformation misses some of the actor documentation; kar files not appearing in the tree misses some.
- *current actor documentation is based on beta2 version
- *problem of free text search engine of listserve.
- I've noted some small questions and comments in red throughout.\\
- In addition, some actors I could not draft copy for because I could not figure out how they worked. Those actors are marked with a TK beside their name in the table of contents.
-
- Additional things to look out for:\\
- #Errors and misrepresentation of actor behavior,terminology, input, or output
- #Inappropriate context (i.e., an actor is described as a GEON actor, with contextual info about GEON, when its scope is much broader. Or, if an actor is described as a generic actor when it should be project-specific)
- #Actors that should be renamed
- #Areas where the docs are too explicit or not explicit enough. The docs are based on the user profiles found here: http://www.kepler-project.org/Wiki.jsp?page=KeplerUsers ), assuming that a user is at least a Quantitative Analyst.
- #Actor docs that are incomplete (the docs do not describe all of the actor functions)
- #Additional actors that should be noted in a particular actor doc (actors that have similar behavior, or that are commonly used in conjunction with the particular actor).
- #Any additional concerns or thoughts
-
- !Additional Actor doc issues to discuss:\\
- #Documentation should be consistent with UI. Whatever convention is used for actor names and parameter names should be incorporated into the docs. Who will decide the standard and implement it in the UI? Who will do this for the docs?
- #Production of Actor docs/incorporation of docs into application. how will this be done? who will do it? Important that <p> are preserved and would like <tt> and <i> to be preserved as well for consistency/ease of recognition.
- #Currently, the beta 2 ontology contains 348 actors. Will any additional actors be included in the release? Will any of the existing actors be removed?
-
- !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)
-
- Notes
- #Is this the type of document that is required?\\
- #If so, what should be added to it? Removed? Reorganized? \\
- #If not, what should the document look like/contain?\\
-
- !Additional questions:\\
- Which workflows will be included in the release?
- ''Note that the outline contains examples (particularly for the project-specific section), but its still unclear which of these will be finalized/included in the demos directory.''
-
- !Additional thoughts about documentation.\\
- Are other documents required? Anything else? \\
- Who will be working on the docs after this meeting?
- ''Note that I'll have only about 20 hours after the meeting.''

Back to Doc Writing, or to the Page History.