[kepler-dev] Re: kepler documentation etc

Tue Mar 8 15:45:45 PST 2005

Matt Jones writes:
 > Hi Laura,
 > 
 > Thanks for the clarifications.  I agree that we need a strong separation 
 > between user and developer documentation.  

agreed

 > I also agree that a cookbook 
 > can not be automatically generated (actually, none of the documentation 
 > can be automatically created, someone has to write it all).  

Some "documentation" should actually be generated automatically, i.e.,
the signatures of actors: Most of the Kepler actors have a fairly
constrained type signature. Those types should be inferrable by
"asking" an actor to provide its port signatures. Yes, some actors
might have varying numbers of ports and their types can be overloaded
(cf. AddSubtract actor) but I guess there are a lot of actors whose
signatures are fairly rigid.

So the "Ptolemy type", the "Unit type" (for the static unit type
system devised by Rowland), and in the near future (still hoping ;-)
the "Semantic type" (better understood now) and the "Transport type"
of actors/ports could all be generated automatically..

Also a kind of documentation...

Bertram

 > However, I 
 > do think the documentation can be written in a framework that allows us 
 > to reuse pieces of it for different purposes, i.e. create different 
 > compilations for different purposes.  For example, a 3 or 4 sentence 
 > user-oriented summary of what a particular actor does is a snippet that 
 > can show up in several places: in an 'actor cheat sheet', in context 
 > accessible help from an actor on a tree or canvas, and anywhere else 
 > where a quick summary of an actor is needed.  Other parts of the actor 
 > description (like details of the input and output ports) would show up 
 > in other places, and all of the actor documentation would be used to 
 > compile a comprehensive reference for actors (probably an appendix in 
 > the Kepler User Guide).
 > 
 > What I would like to see happen is that these different documentation 
 > efforts be coordinated enough to be able to use the pieces in these 
 > various ways.  Even more importantly, its critical not to have several 
 > different 'summaries' of any particular actor because that makes 
 > maintenance of the documentation a nightmare.  Rather, each piece of 
 > documentation we write should have a distinct purpose and be maintained 
 > in a reusable framework.  (BTW, this means documentation can not be 
 > stored as word documents).
 > 
 > Towards this end, we have been trying to compile a complete list of 
 > documentation products for Kepler and fit it into a framework.  Ilkay is 
 > taking the lead on that, and it is described here:
 > http://kepler-project.org/Wiki.jsp?page=KeplerDocumentationFramework
 > 
 > Please review it.  If your 'cookbook' or any other documentation item is 
 > not covered by that list, please add a detailed comment at the bottom of 
 > the page describing what is missing.   I think we envisioned our 
 > "Getting Started with Kepler" guide as containing the sort of cookbook 
 > tutorials that you are describing.  But please provide feedback if we're 
 > missing something.   Ilkay will then try to reconcile your comments with 
 > what's in the page, and you can review that and we'll iterate until 
 > everyone is happy.  Then we can build the framework and everyone can 
 > contribute to writing the documentation.  I am hoping to create a bug 
 > for each writing task that can be associated with a bulleted item in the 
 > documentation plan web page so that we know who is leading each writing 
 > effort.
 > 
 > Specifically for actors, our plan is to have developers write the first 
 > draft documentation for the actor when they first create the 
 > documentation, and then have a scientist revise/re-write it to be sure 
 > it meets our users needs.  Then the developer would review these 
 > revisions to make sure everything is still technically accurate.
 > 
 > For other parts of the documentation, I think its more appropriate for 
 > non-developers to write these things from the beginning.  The Getting 
 > Started guide is a good example, as it really needs to come from a user 
 > perspective.  So we were hoping that you, Sam, and Deana (an others from 
 > GEON, etc) could help out with these writing tasks.  I think they will 
 > be exactly the sort of products envisioned in your task list from the 
 > BEAM meeting (or they will be, after everyone provides feedback on the 
 > documentation plan).  So, we can communicate the shift in exact tasks to 
 > Bill and anyone else by telling him we've refactored things and point 
 > him to the web page.
 > 
 > I'm sending this email to kepler-dev as it really needs to be a 
 > kepler-wide effort anyways.  Lets try to move these discussions onto 
 > kepler-dev so that everyone can benefit from the interactions.
 > 
 > Cheers,
 > Matt
 > 
 > 
 > Laura L. Downey wrote:
 > > Hi Matt,
 > > [material elided]
 > > In terms of Kepler documentation, I think I understand what has been 
 > > proposed from reading the emails and also from talking with Deana.  I 
 > > just want to emphasize that regardless of implementation we definitely 
 > > want to have user documentation and programmer/technical documentation.  
 > > To that end, I need to look at the doc templates and most likely suggest 
 > > a few additions.
 > > 
 > > However I'm not sure there is any way to "generate" the cookbook from 
 > > this.  The way I envision the cookbook is as a procedural manual for a 
 > > few things -- like creating some simple workflows with input data, some 
 > > processing and specifying the output.  And possibly even including a 
 > > section on how to add an actor etc.  This would involve telling the user 
 > > or programmer what information they need before they start, the steps to 
 > > follow, and the expected results.  It is not as full blown as a tutorial 
 > > which has lots of explanations etc.
 > > 
 > > In terms of the cookbook (which I think is extremely important), I 
 > > volunteered to be involved because it will be helpful to me in better 
 > > understanding Kepler if I have to formulate some of this.  Now I 
 > > understand from Deana that you guys may not want me to be heavily 
 > > involved in the writing process because of possible demands on my time.  
 > > Sam and I discussed this briefly earlier today and we may use the 
 > > approach that I sort of outline what is needed and how things will be 
 > > structured and we discuss some of the content, then she'll put things 
 > > together, write them up and then I'll edit as needed.  Will this be 
 > > acceptable?
 > > 
 > > Now I also need to mention that as a result of the BEAM workshop, Bill 
 > > made some assignments for us all.  The following is what I am involved 
 > > in and was assigned to lead:
 > > 
 > > *Kepler End-User Issues (Laura will lead and schedule this activity):*
 > > ·        *User documentation *
 > > o       *HIGH.** cheat sheets (Samantha)*
 > > o       *(HIGH for ESA).** cookbooks (example workflow documentation) 
 > > (Laura, Dan, Chad)*
 > > ·        *Guided analysis (wizards) (Laura, Kepler developer) *
 > > ·        *HIGH.** Develop good installation capability (Dan)*
 > > o       *Kepler first*
 > > o       *R, etc.*
 > > ·        *HIGH.** Instructional use (Mark, Deana, Samantha)*
 > > 
 > > * *
 > > 
 > > All things considered, I think things definitely affect these 
 > > assignments . . .  so I guess I need to understand how to shift based on 
 > > the current plan and to let Bill know.  Basically on the things I’m not 
 > > specifically assigned to do I was going to gather status and/or prompt 
 > > people on the various items.  But with the direction you are going, it 
 > > seems like the cheat sheet may be something that is generated, and I’ve 
 > > already mentioned how Sam and I might approach the cookbook.  The 
 > > remaining assignments I can still just gather status on from Dan and 
 > > Mark and Deana.
 > > 
 > > Laura L. Downey
 > > 
 > > Senior Usability Engineer
 > > LTER Network Office
 > > Department of Biology, MSC03 2020
 > > 1 University of New Mexico
 > > Albuquerque, NM  87131-0001
 > > 505.277.3157 phone
 > > 505.277-2541 fax
 > > ldowney at lternet.edu
 > 
 > -- 
 > -------------------------------------------------------------------
 > Matt Jones                                     jones at nceas.ucsb.edu
 > http://www.nceas.ucsb.edu/    Fax: 425-920-2439    Ph: 907-789-0496
 > National Center for Ecological Analysis and Synthesis (NCEAS)
 > University of California Santa Barbara
 > Interested in ecological informatics? http://www.ecoinformatics.org
 > -------------------------------------------------------------------
 > _______________________________________________
 > kepler-dev mailing list
 > kepler-dev at ecoinformatics.org
 > http://www.ecoinformatics.org/mailman/listinfo/kepler-dev