User Facing Documents Task Force
This page has been updated in May 2008. The document details section now lists some of the user facing work products that have been developed or proposed by members of this group.
Help the Working Group produce various less technical documentation aimed primarily at those who wish to use OWL, rather than those who plan to implement OWL tools.
Produce "editors' draft" level material, for Working Group review, in time for the Boston Face to Face.
Documents with a strong user facing role that are mentioned by the charter include an Overview, Requirements document, Descriptive specification, and a User guide. These roughly correspond to the OWL 1.0 documents Overview, Requirements, Reference and Guide.
Work products that have been undertaken or proposed by members of this task force to address the needs of users of OWL 2 include:
- A Primer intended to provide a short introduction to OWL, including a conceptual orientation.
- Revision of the Structural Specification and Functional-Style Syntax document so that it may play the role of a language reference for both users and implementers.
- A Quick Reference Guide resource meant to be a quick reference for new and occasional users.
- A New Features and Rationale document intended to capture new features, use cases and requirements that motivated changes and additions to OWL seen in OWL 2.
(related link Requirements work space)
- A Cookbook resource that would describe patterns and tricks for using OWL 2.
Telecons will be by arrangement and as needed. Usual time is Monday at 7am PST /10 am EST/3 pm GMT/4 pm CET. Usual duration is 60 minutes.
- Teleconference 21 July 2008
see entry in Meetings for agenda
Task Force Issuettes
Things we would like to resolve as a task force, and then ask for WG approval (if needed).
Who are the users
Which documents to do first
Who leads the charge on each document
Note: appointment of editors is the gift of the WG chair.
What's good documentation
- Bijan Parsia likes the RDF/XML Syntax Spec Section 2 which he says "is the single best non-tutorial intro to the language. I've used it in classes; I've used it myself." email
- Rinke's views
- Martin Dzbor
- "view from the outside"
- Bijan described his point of view during 7 Nov 2007 meeting
- Vipul described his point of view during 15 Nov 2007 meeting
What do we want in a Reference document
Examples of "good" reference documents and/or key characteristics of such documents.
- EvanWallace finds The Unified Modeling Language Reference Manual by Rumbaugh, Jacobson, and Booch and A C Reference Manual by Harbison and Steele to be prototypes for language reference manuals. The Encyclopedia of Terms is the key section of the UML Reference Manual. It provides sections for each of the constructs of the language with standard subsections where applicable in the same order each time. The form for these sections is typically:
- the name of the construct,
- a short (typically one sentence) description of the construct,
- see also references to closely related constructs,
- a subsection describing what the construct means,
- a subsection describing the notation/syntax to express the construct often including an example and
- sometimes a discussion subsection making key points or clarifying aspects of use of the language that may be subtle or often missed.