[kepler-dev] Re: kepler documentation etc

[Matt Jones]

Hi Laura,

Thanks for the clarifications.  I agree that we need a strong separation 
between user and developer documentation.  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).  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
-------------------------------------------------------------------