This page is a summary of the "Best Practice Recipe" issues presented in a QA review by Karl Dubost in May 2006. The version reviewed by Karl was the 14 Mar working draft, which has been obsoleted by newer revisions.
See also ISSUE-18 in the tracker.
Contents
Abstract
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0066
[[[ This document describes best practice recipes for publishing an RDFS or OWL vocabulary or ontology on the Web. The features of each recipe are clearly described, so that vocabulary or ontology creators may choose the recipe best suited to the needs of their particular situations. Each recipe contains an example configuration for use with an Apache HTTP server, although the principles involved may be adapted to other environments. The recipes are all designed to be consistent with the architecture of the Web as currently specified. ]]] -- Best Practice Recipes for Publishing RDF Vocabularies http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/ Tue, 14 Mar 2006 12:48:26 GMT I'm not sure that people know what are - RDFS vocabulary - OWL vocabulary "Ontology on the web" makes perfect sense. Maybe the document should start with: This document describes best practice recipes for publishing vocabularies or ontologies on the Web (in <acronym title="Resource Description Framework">RDF</acronym> Schema or <acronym title="Web Ontology Language">OWL</acronym>). "The features of each recipe are clearly described, so that vocabulary or ontology creators may choose the recipe best suited to the needs of their particular situations." *clearly* is usually abusive, this is the intent, it doesn't mean it's how the reader will perceive it. Maybe write something like that, lighter, shorter. An ontology is a kind of vocabulary, repeating the words might make the text a bit heavy. "The features of each recipe are described in details, so that vocabulary designers may choose the recipe best suited to their needs." "Each recipe contains an example configuration for use with an Apache HTTP server, although the principles involved may be adapted to other environments. " I would write this the other way around :) "Each recipe introduces general principles and an example configuration for use with an Apache HTTP server (which may be adapted to other environments)." btw, here there's a good opportunity to create a template and/or invite people to submit bindings to the Mailing List, id est how people applied this recipe in this particular server environment, Web Apps Framework, HTTP Servers only, etc. That would help other people to find the information. With a proposed template, it would help people to collect, gather the information. Maybe a link to the Architecture of the Web document too. :)
Response:
"ontologies on the web": changed in the document, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#abstract.
"clearly/in detail": changed in the document, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#abstract.
"Apache configuration": changed in the document, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#abstract.
Templates: added to the document, see ISSUE-19.
Architecture of the web: new reference added in the Introduction, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#secintro.
Introduction
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0067
[[[ Introduction This document is intended for the creators and maintainers of RDFS and OWL vocabularies or ontologies. (In this document, vocabulary and ontology are used interchangeably.) It provides step-by-step instructions for publishing vocabularies on the Web, giving example configurations designed to cover the most common cases. For more information about RDFS and OWL see [RDFS, RDFPrimer, OWLGuide, OWLFeatures]. ]]] -- Best Practice Recipes for Publishing RDF Vocabularies http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#secintro Tue, 14 Mar 2006 12:48:26 GMT I'm not sure if sentences with parantheses in isolation are correct in English. I may be wrong. What about "This document is intended for the creators and maintainers of vocabularies in RDFS and OWL (Vocabulary and ontology are used interchangeably in the context of this specification)." [[[ This document is presented as a 'cookbook' of 'recipes'. Each recipe takes the reader through the steps needed to publish a vocabulary on a Web server and to configure the Web server to support Semantic Web applications. The section choosing a recipe provides guidance on which recipe is most appropriate for your situation and requirements. Once you have chosen a recipe, follow the steps given, adapting the examples for your particular vocabulary. ]]] -- Best Practice Recipes for Publishing RDF Vocabularies http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#secintro Tue, 14 Mar 2006 12:48:26 GMT Avoid too much repetition (This document…) Use appropriate English quotes “” Do not change the style from neutral (reader) to direct (you). This “cookbook” gives “recipes” describing the steps needed 1. to publish a vocabulary on a Web server, 2. configure the Web server to support Semantic Web applications. The section “Choosing a recipe” provides guidance for choosing the most appropriate recipes depending on the situation and the requirements. Once the recipe has been chosen, the reader can follow the steps, adapting the examples for a particular vocabulary. Two good references for writing (I know how much it's difficult to see the mistakes we do when we are working on something, I do all the times.) * Manual of Style http://www.w3.org/2001/06/manual/ * The Elements of Style http://www.bartleby.com/141/
Response:
Sentence in parenthesis: changed in the document, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#secintro.
Repetition, quotes and style: changed in the document, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#secintro.
Apache Configuration - performance
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0072
[[ If you do have write access to the main Apache configuration files, you might consider writing the configuration directives directly there, as using per-directory configuration can negatively affect server performance, see [APACHE20]. ]]] -- Best Practice Recipes for Publishing RDF Vocabularies http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#apache Tue, 14 Mar 2006 12:48:26 GMT Could you give a link to the prose where the performances problem are explained. The link is just given to the Apache Documentation. [[[ The first of these is performance. When AllowOverride is set to allow the use of .htaccess files, Apache will look in every directory for .htaccess files. Thus, permitting .htaccess files causes a performance hit, whether or not you actually even use them! Also, the .htaccess file is loaded every time a document is requested. ]]] -- Apache Tutorial: .htaccess files - Apache HTTP Server http://httpd.apache.org/docs/2.0/howto/htaccess.html#when Sun, 15 Jan 2006 20:27:52 GMT
Response:
A more specific link is provided, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#apache.
Apache Configuration - media type
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0073
[[[ The appropriate content type for serving RDF/XML content is 'application/rdf+xml'. An Apache server can be configured to recognize files with the '.rdf' extension and serve them with the appropriate content type, by adding the following directive to the main configuration file: AddType application/rdf+xml .rdf ]]] -- Best Practice Recipes for Publishing RDF Vocabularies http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#ref-APACHE20 Tue, 14 Mar 2006 12:48:26 GMT Please, give the reference to the RFC defining the media type for RDF: RFC 3870. [[[ This document describes a media type (application/rdf+xml) for use with the Extensible Markup Language (XML) serialization of the Resource Description Framework (RDF). RDF is a language designed to support the Semantic Web, by facilitating resource description and data exchange on the Web. RDF provides common structures that can be used for interoperable data exchange and follows the World Wide Web Consortium (W3C) design principles of interoperability, evolution, and decentralization. ]]] -- http://www.ietf.org/rfc/rfc3870.txt Tue, 07 Sep 2004 18:57:17 GMT
Response:
Reference to RFC 3870: added, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#setting_type.
URI namespaces
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0074
URI namespaces http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#naming Please, move this section to an appendix. It is not part of the main topic of your document. It's very helpful, but it will better at the end of the document as a reference.
Response:
This section is now Appendix B, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#naming.
Choosing a Recipe
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0075
"Choosing a recipe" http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#choosing This section will benefit from a summary table of all cases, it will make the prose lighter by just explaining what are the different cases. A benefit analysis for each case would be good too. Why? When? hash slash namespace namespace ============================================================ machine processable RDF recipe 1 recipe 2 (PURL) recipe 1a recipe 2a ------------------------------------------------------------ RDF and Single HTML document recipe 3 recipe 4 (PURL) recipe 3a recipe 4a ------------------------------------------------------------ RDF and Multi HTML documents recipe 5 recipe 6 (PURL) recipe 5a recipe 6a ============================================================ Btw there's a typo in the section recipe 5, I think it's "If you are using a HASH namespace.
Response:
Added table, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#recipe_table.
Typo in section Recipe 5: fixed, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#recipe5.
Behavior
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0077
[[[ Note that where the server is to be configured to perform content negotiation, a 'default behavior' must be specified. The server must be able to determine which response should be sent in the case where the client does not include an 'Accept:' field in the request message header (i.e. the client doesn't specify a preference), or where the values of the 'Accept:' field do not match any of the available content types (i.e. the client asks for something other than RDF/XML or HTML). ]]] -- Best Practice Recipes for Publishing RDF Vocabularies http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#negotiation Tue, 14 Mar 2006 12:48:26 GMT The second sentence is too long and the paragraph difficult to read. Suggestion: "The server must be configured with a “default behavior” to perform a content negotiation, because sometimes 1. the client does not send an 'Accept:' field in the request message header i.e. the client doesn't specify a preference) 2. the client send values of the 'Accept:' field which do not match any of the available content types (i.e. the client asks for something other than RDF/XML or HTML)." Please, move the note about IE6, or comment about IE6 in a separated paragraph as an example of implementation problems. Did you test with other user agents (search engine bots, screen reader, voice reader, etc.)?
Response:
Section too long: the paragraph has been rephrased according to suggestion, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#default.
Note about IE moved to a new subsection, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#defaultIE.
- Tested with other agents: manually tested with most common web browsers (including IE7). Also, a new online validation service is now available.
Writing style
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0078
Often in the document, the editors are writing “this” like in This recipe This document Please review the document to remove them as much as possible and write directly about the content. It is often a question of rewriting the paragraph in such way that it is obvious, the paragraph is about this recipe or this document. I gave examples of rewriting in previous comments.
Response:
- Changes have been made according to suggestion.
Recipes in General
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0079
The recipes are clear in general. The graphics are more than welcome. Really cool. * Do not use too much the “…” and write it “…”, not “...” * Is the working group sure that the domain “isegserv.itd.rl.ac.uk” will *always* be active? If not, use either example.org, or use a space on w3.org as a practical example. Location: http://isegserv.itd.rl.ac.uk -> Location: http://example.org
Response:
- Ellipsis: changed character according to suggestion.
- Domain: the examples have been moved to w3.org space.
Apache Configuration - Appendix
http://lists.w3.org/Archives/Public/public-swbp-wg/2006May/0080
Apache Configuration section. http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/#apache * Appendix Please, move this section to an appendix. It is not part of the main topic of your document. It's very helpful, but it will better at the end of the document as a reference.
Response:
Section has been moved to Appendix D, see http://www.w3.org/TR/2008/NOTE-swbp-vocab-pub-20080828/#apache.