The I throughout is Bijan. This page started as an email but felt unreadable with all the uris.

Primer

Peter and I have been working on a primer (see the version with global syntax switching). (These are not yet in the wiki so we can freely hack javascript).

The primer is intended to meet the Overview and User Guide deliverables (it's not feature complete). Note that this version may not display correctly (or at all) in Internet Explorer (IE users can try this version). Both work fine in Firefox, Safari, or Opera.

Description/Reference

I've been working on various ways of restructuring the structural specification to make it more accessible and reference like.

Btw, you can see a version that has controls allowing you to hide the UML diagrams or the Grammar productions if you don't want to see them.

The Structural Reference Experiment is intended to (partially) meet the Formal Specification and Descriptive Specification deliverables.

I also started work on an analytical index but it's not progressed very far because I tried again to do css in the wiki...and failed :(

Formal Docs

I added sections to the semantics document to parallel the relevant sections in the StrucRef

I plan to do this for the RDF mapping as well, so the structure is parallel in all three. I've not added cross links yet.

Issues and Ideas

These are all in a preliminary/proof of concept/exploration stage. Not all the ideas I have have been demoed yet. I welcome constructive suggestions and feedback.

Descriptive text and notes

Not much extra has be added yet. I've been concentrating on structure. I think there were surprising (to me) gains gotten just with structural improvements.

Granularity of Sections

Boris and I have been discussing is whether to have larger subsections that are "topically" grouped as you can see in the Class Expressions section or have a section per term as the old reference did. There are arguments both ways. I'm interested in what people think on this.

I think in either case that it would not be difficult to mark all the sections so one *could* pull together the struc spec, the semantics, and the mapping of your choice into one nice manual.

Analytical Index

I'm not sure that's the right term, but I think an index is not a bad idea regardless of the level of granularity of the sections.

Each term will have a set of buttons beside them which take you to the corresponding part of the strucref, the semantics, etc.

I would like to do some text pop ups in the index so you can quickly mouse over the terms and get a bit of info. This could also work for the UML diagrams.

Printing

All the documents will be printable in their default state and degrade gracefully.

How examples work

I have an example for the ontologies section and one parital one for the propositional connectives. I'm not sure exactly what format would be best.

Feedback

Please look at the animated ascii art dancing kitten so you are in a good mood :)

Background on the Proposal

The OWL WG is chartered to develop a new OWL specification. In its charter, that specification is described as having a number of components (which, following charter terminology, I will call deliverables). Some deliverables are described in terms of functionality and (partially) by reference to OWL 1.0, e.g.:

Descriptive specification: A less formal, but still comprehensive and systematic, specification of the language's syntax and semantics (see, e.g., OWL Reference).

The charter makes clear that we do not have to update the OWL Reference or even have a document (much less Rec track document) called "Reference"):

Each component may consist of one or more documents, and may or may not extend existing OWL documents.

So the WG has to decide how it wants to meet these deliverables. One obvious proposal is to "refresh" the old documents (Guide, Reference, and Overview, primarily). This has some support in the working group, but also strong (in intensity) and large (in numbers) opposition, as can be seen from F2F1_Minutes#User_Facing_Documents. Instructive are the straw polls (there was some confusion in the polling and the minuting, so the following is my best understanding):

I have worked with the OWL 1.0 documents for many years in several different capacities and I spent a fair bit of the time in Nov-Dec 2007 reading them over with a fresh eye, thinking about their strengths and weaknesses, and listening to people talk about what they liked and didn't like. Here are a few (non-exhaustive) points of criticism:

• There are too many documents, which are themselves large, without clear distinguishing purpose or progression, with a lot of repetition. Thus, they can be very intimidating and frustrating for people. (Consider overview and reference which are both "reference like" but have completely different styles and content.)
• The are very vocabulary/species/namespace oriented, which makes it harder to grasp the language in larger chunks. (That is, they don't establish a helpful cognitive map. This is important for both learning and reference.)
• There are technical errors and misleading aspects.
• They are very distant from the actual specification.
• Their structure makes retargeting, virtual reorganization, updating, and reuse difficult.

A point Deb raises repeatedly:

• Some (i.e., her) users rely on the old documents as W3C recommendations.

I am afraid that I don't understand this argument. If there are users who rely on the specific documents because they work well for them or are integrated into their training/documentation, then surely it doesn't matter whether they are a W3C recommendation. What matters is that they are available. (By analogy, one generally doesn't care who the publisher of a dictionary is so long as you can get copies of the dictionary and they are appropriately updated.) However, at the F2F I suggested that we get the W3C to release the old documents under a more permissive license so that Deb could update the documents for her users. But apparently this is not sufficient. Even releasing them as WG notes (a move I don't support, but probably would get more support in the WG) wasn't deemed sufficient. So I am confused about what the requirements (with their rationales) are.

There are two points raised in various contexts:

• The WG doesn't have enough resources to make new documents. Refreshing the old is easier.
• There are marketing advantages to refreshing the old documents, including enhancing the perceived stability of OWL.

It's pretty clear to me, having looked at them, that refreshing the old documents, even in place, is a fairly difficult task. As no one has come forward to do this refreshing on spec, I conclude that intrinsic interest is low as well. On the other hand, Peter and I have done a fair bit of work, purely on spec, and the current results are, I would say, highly promising. I think we can go much further down the quality trail under my proposal.

As for the second point, I just don't get it. First, I don't see that most users identify stability with a language with stability of its documentation. I've never heard this argument made in any other context. Second, I hope we all imagine the set of future OWL users to be the much larger set. So the documentation we produce will be the documentation they know.

Thus, I made a proposal at the first F2F:

• That we have a "primer" document that would meet the "overview" and "guide" deliverables.
• That we enhance the structural specification to cover the "descriptive specification" (aka reference) deliverable.
• That we enhance the other formal docs so that cross links from the primer and strucspec are sensible
• That we use modern web documentation features for flexible presentation.

It was clear that this proposal had interest, but several people didn't quite see how it would work or whether it was feasible. Thus I was tasked (and Peter graciously jumped in to help) produce enough of this approach (a proof of concept) that the WG could make a more informed decision.

If there are parts of the proposal that you don't understand how they'd work and need a mock up for, please let me know.