[kepler-dev] agenda for kepler meeting

[Matt Jones]

I agree, these are nice suggestions for documentation.  In addition, I 
think we can go further.  The process of documenting actors and 
workflows is tightly tied to the process of doing semantic registration 
as we've discussed with you and Shawn.  We talked a bit about semantic 
registration during this kepler meeting in SB over the last two days, 
and have some kepler-specific tasks to follow up on with you and Shawn. 
  If we have both natural language documentation and formal semantic 
registrations as documentation, it would be nice if they could be stored 
together.  Chad has the task of following through on designing, with 
KR/SMS folks, a precise solution to storing the registration mappings 
for actors, workflows (MoML), web services (WSDL), and data (EML).  This 
is a necessary precursor to our ability to implement the ontology-driven 
browsing features that we discussed (also a major topic of our meeting).

Cheers,
Matt

Bertram Ludaescher wrote:

> Edward:
> 
> These are great suggestions! Let's see what the few and the brave
> getting together over the next two days come up with.
> 
> But your suggested system sounds very cool..
> 
> 
> Bertram
> 
> 
> 
>>>>>>"EAL" == Edward A Lee <eal at eecs.berkeley.edu> writes:
> 
> EAL> 
> EAL> At 10:18 PM 6/2/2004 -0700, Bertram Ludaescher wrote:
> 
>>>g) documentation standards: e.g., we might have a certain minimal
>>>template for a "manpage" style documentation of each actor that goes
>>>in the cvs repository. This can be part of the Java doc, but it should
>>>be clear how those look like and what is expected. I think overall at
>>>least the following are needed:
>>>
>>>g1) actor documentation (for users); similar to "man <actor>"; for the
>>>command line challenged those could come up when one right clicks on
>>>an actors and asks "get documentation". This is already in place
>>>thanks to Ptolemy/Vergil but we need some conventions what goes in the
>>>javadoc for an actor
>>>
>>>g2) workflow documentation: there may be two versions of it "Outreach"
>>>and "Real User". The former may be include a snapshot with an overview
>>>and a page or two explaining what the workflow does and how it
>>>works. The "Real User" documentation views a workflow as "serious
>>>application" and is thus user manual for that specific workflow... we
>>>probably won't have those anytime soon!?
> 
> EAL> 
> EAL> On these, I have two comments:
> EAL> 
> EAL> 1) Ptolemy Classic had a very nice actor documentation feature
> EAL>     that we could emulate.  We would implement it as a Doclet,
> EAL>     so it would use the same source code that is used by Javadoc.
> EAL>     But the documentation that it generates would look very
> EAL>     different.  Whereas the Javadoc emphasizes the object-oriented
> EAL>     to an actor, our documentation needs to emphasize its
> EAL>     actor-oriented interface.  Something like:
> EAL> 
> EAL>     ActorName: First sentence of the class documentation.
> EAL>     Parameters:
> EAL>       - firstParameter: Documentation from javadoc for the public member.
> EAL>       - ...
> EAL>     Input ports:
> EAL>       - firstPort: Documentation from javadoc for the public member.
> EAL>     Output ports:
> EAL>       - secondPort: ...
> EAL>     Details:
> EAL>       The entire class documentation.
> EAL>     See also: hyperlinks to related actors.
> EAL>     Demos: hyperlinks to demos.
> EAL>     Tests: hyperlinks to tests.
> EAL>     Base class: hyperlink to base class doc (which is Javadoc if there
> EAL>       is no actor doc).
> EAL> 
> EAL>     All of this could be done as a doclet... It's just work...
> EAL>     The output would be HTML, or better yet, XML for viewing with
> EAL>     a style sheet (but we have to be sure the HTML renderer in
> EAL>     Java supports the style sheet). When viewed within Ptolemy II,
> EAL>     the hyperlinks would open the relevant models.
> EAL> 
> EAL> 2) Rowland Johnson added to version 4.0 a Documentation attribute
> EAL>     that you can drag into a model and double click on to view
> EAL>     the documentation of the model.  This could be augmented to
> EAL>     generate the boilerplate for documentation like the actor
> EAL>     documentation above, if the documentation doesn't already
> EAL>     exist.  If the documentation does exist, it should parse the
> EAL>     HTML/XML and make it consistent with the model (e.g., the
> EAL>     ports or parameters may have changed).
> EAL> 
> EAL>     The current version simply looks for the doc file in a standard
> EAL>     place, and not finding it, presents a file browser.  This is not
> EAL>     that useful, but augmenting it as above would be a big help at
> EAL>     relatively modest cost in effort.
> EAL> 
> EAL> These two things are on my to-do list, but my to-do list is pretty
> EAL> big still...
> EAL> 
> EAL> Edward
> EAL> 
> EAL> 
> EAL> 
> EAL> ------------
> EAL> Edward A. Lee, Professor
> EAL> 518 Cory Hall, UC Berkeley, Berkeley, CA 94720
> EAL> phone: 510-642-0455, fax: 510-642-2739
> EAL> eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal