Doc Writing

This is version 23. It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

Documentation writing workshop

Coos Bay in GoogleEarth

LTER Reimbursement page

Objective

Agenda

• review GSG

• Actor Documentation
• functionally group actors by science/domain specific
• groups of twos review documentaion
• discuss/define actor documentation user
• basic requirements must be able to some quantative skills; basic programming language;

Thursday pm

• User Manual
• wrap up and action points

Pre-workshop deadlines:

• Technical notes due from developers by June 1
• Menger-Anderson (technical writer) to work July 1-Aug 30 (6 weeks contract work)
• Read documentation drafts prior to meeting
• Getting Started Guide
• Actor documentation
• Outline of User Guide

Action Items:

Getting Started Guide

• 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.
• Remove Appendix 8.2 “Technical Overview of Kepler”
• Create a stand-alone glossary (actor, relation, token, float, double, data type, port, channel, relations, components, etc)
• Clarify Data Actor (“widget that supplies the data/not the data”)
• 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.
• 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). Program
• Add paragraph with references to other systems (Stella; Simulink (kepler like), R, Matlab, Excel, SAS)
• 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.
• 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.
• 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?)—Sam will do this

Related tasks discussed:

• Make the listserv searchable (Mark Schildhauer)
• Gap between this and building your own workflow
• Clearly defining token; actor as vehicle
• create a list of all changes to screenshots and work with NCEAS/UCSB people on creating screenshots. (Samantha)

• 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

• 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

Actor Documentation

• 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.

Additional things to look out for:

1. Errors and misrepresentation of actor behavior,terminology, input, or output
2. 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)
3. Actors that should be renamed
4. 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.
5. Actor docs that are incomplete (the docs do not describe all of the actor functions)
6. 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).
7. Any additional concerns or thoughts

Additional Actor doc issues to discuss:

1. 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?
2. 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.
3. 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

1. Is this the type of document that is required?
   
2. If so, what should be added to it? Removed? Reorganized?
   
3. If not, what should the document look like/contain?
   

Additional questions:

Additional thoughts about documentation.

Participants (6 budgeted to travel)

• Matt Jones
• Deana Pennington
• Samantha Katz
• Kirsten Menger-Anderson
• Tim McPhillips
• Dan Higgins
• Josh Madin
• Ilkay Altintas
• Mark Schildhauer

CoosBay-OIMB.kmz

1187 bytes