[VM] Looking at Javadoc, dreaming of RDFdoc

Reading section 2. of the current draft
http://www.w3.org/2001/sw/BestPractices/VM/principles/20050513,

"As a bare minimum, a list of the terms should be published, with text
definitions."

Looking at the heteroclit publication styles and formats of currently published RDF
vocabularies,

Looking OTOH at the Javadoc format,

Being myself in the process of trying to improve documentation style of Mondeca
ontologies,

Seems to me we could provide some more precise guidelines for documentation stylesheets,
and maybe dream about something in the future that would be to RDF what Javadoc is to
Java. What Alistair has done at http://www.w3.org/TR/swbp-skos-core-spec/ seems something
close to perfection (yes, yes).

I also looked at what is done at Schemaweb http://www.schemaweb.info/. The layout of
schemas here is pretty minimal, but clean. Dan, would you say that
http://www.schemaweb.info/schema/SchemaInfo.aspx?id=29 is a sufficiently usable
publication of FOAF vocabulary? In any case it's easier to find there than at
http://www.foaf-project.org/ where it's hidden under developers / spec which will be
skipped by anyone but techies ;-) Seriously, this brings back the question of Tuesday's
telecon : what is the intended audience?

BTW Alistair : How do you edit your nice tables for SKOS spec, do you use a stylesheet
appplied directly to the RDF file? Actually, people need answers to such very basic and
naive questions. When you come to vocabularies with hundreds of elements, they are getting
critical.
There are a few stylesheets around, like http://vocab.org/2004/03/toolchain/ but I have
not tried them.
The results look like http://vocab.org/relationship/ which has quite a rough design, but
is at least clean and readable.

Other ideas? Do you think paving the way to RDFdoc is in our charter / bandwidth? At least
this section 2 could point at some good-looking practices, and maybe open the door to
future standardisation.

Bernard

**********************************************************************************

Bernard Vatant
Senior Consultant
Knowledge Engineering
bernard.vatant@mondeca.com

"Making Sense of Content" :  http://www.mondeca.com
"Everything is a Subject" :  http://universimmedia.blogspot.com

**********************************************************************************

> -----Message d'origine-----
> De : Thomas Baker [mailto:thomas.baker@bi.fhg.de]
> Envoyé : lundi 6 juin 2005 19:10
> Ŕ : SW Best Practices
> Cc : Bernard Vatant
> Objet : Re: [VM] Agenda for June 7 telecon
>
>
> On Mon, Jun 06, 2005 at 10:15:25AM +0200, Bernard Vatant wrote:
> > > > > Next telecons:
> > > > >
> > > > >    June 7, Tuesday, 1300 UTC
> >
> > Is there an agenda posted somewhere?
>
> Agenda - Vocabulary Management telecon, Jun 07, 1300 UTC (1500 Amsterdam)
>
> Zakim: +1.617.761.6200
> Conference code 8683# ('VMTF')
> irc://irc.w3.org:6665/vmtf
>
> 1. Report from the last Telecon, May 12
>    http://lists.w3.org/Archives/Public/public-swbp-wg/2005May/0085.html
>
> 2. "Basic Steps for Managing an RDF Vocabulary" - next steps
>    http://www.w3.org/2001/sw/BestPractices/VM/principles/20050513
>
> 3. "Some Things that Hashless URIs can Name" - next steps
>    http://www.w3.org/2001/sw/BestPractices/VM/httpclass/1
>
>
> --
> Dr. Thomas Baker                      baker@sub.uni-goettingen.de
> SUB - Goettingen State                            +49-551-39-3883
> and University Library                           +49-30-8109-9027
> Papendiek 14, 37073 Göttingen

Received on Thursday, 9 June 2005 14:25:37 UTC