Re: Documentation goals

Hi Alan,

On 3 nov 2007, at 07:25, Alan Ruttenberg wrote:
> I'm not exactly sure how one draws the line here. Personally, I  
> don't see work on educational material as harmful, as long as it is  
> well done and doesn't compromise other goals of the group. I don't  
> see the latter happening currently, so I guess I'm taking a wait and  
> see attitude towards the efforts of the people who plan to work on  
> the documentation.

Sure, that sounds sensible, it is certainly not my intention to veto  
any such efforts!

> We will need to assess the work they do, and it would certainly help  
> if they have input from all of us about what we think is important  
> to have in the documentation. To that end, maybe clarifying the  
> distinction you are trying to make could help.

I think minimal understandability of the specification, can be  
achieved through making explicit the intentions and reasons behind  
each document and element of the specification. Things like a  
comprehensive overview (as investigated by the UFDTF), but also inline  
examples of every language construct, and a clear synopsis of every  
document can really help here. I guess this could include use cases as  
well (as teasers).

Educational material, on the other hand, would include e.g. a full  
tutorial (e.g. Protege's Pizza tutorial), or full-fledged guidelines  
for modelling (as e.g. done by the SWBP group).

The distinction is primarily the `direction' in which such documents  
are written. The former takes the specification as focal point, and  
presents it in a compelling way to readers: outreach. The latter would  
take the user as focus, and unveils the specification in a  
didactically adequate way. The problem with a strong focus on users is  
that there are so many of them: a document explaining the standard for  
a life sciences or medicine oriented audience is not very adequate for  
people in government, law, environment, science, philosophy,  
education, etc. etc. In short: the effect may be the converse of  
what's intended.

> One way to make this and other points on documentation might be to  
> identify some from other analogous projects that people have found  
> to be particularly useful to them or know to have been useful to  
> others, and perhaps some examples that have elements that we want to  
> avoid.

Good point, I will try to come up with some examples.

Best,

	Rinke


----------------------------------------------
Drs. Rinke Hoekstra

Email: hoekstra@uva.nl   Skype:  rinkehoekstra
Phone: +31-20-5253499    Fax:   +31-20-5253495
Web:   http://www.leibnizcenter.nl/users/rinke

Leibniz Center for Law,         Faculty of Law
University of Amsterdam,           PO Box 1030
1000 BA  Amsterdam,            The Netherlands
----------------------------------------------

Received on Monday, 5 November 2007 09:53:51 UTC