Doc Writing

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

Documentation writing workshop

When: September 7-8, 2006 (starts at noon Sept 7)
Where: Oregon Institute of Marine Biology (OIMB), Coos Bay, Oregon
Hotel: Red Lion, Coos Bay
GoogleEarth: Coos Bay in GoogleEarth

Objective

Review and revise the documentation for the Kepler system to prepare it for a 1.0 release.

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

For discussion:

Getting Started Guide

Please note any errors, any necessary additions or deletions, any other thoughts or feedback.

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

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.

Participants (6 budgeted to travel)

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

Attachments:

CoosBay-OIMB.kmz

1187 bytes

Go to top More info... Attach file...

This particular version was published on 31-Aug-2006 07:13:35 PDT by uid=sromanello,o=LTER.