This is an archive of an inactive wiki and cannot be modified.

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

  1. Abstract
  2. Introduction
  3. Apache Configuration - performance
  4. Apache Configuration - media type
  5. URI namespaces
  6. Choosing a Recipe
  7. Behavior
  8. Writing style
  9. Recipes in General
  10. Apache Configuration - Appendix

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:

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:

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:

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:

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:

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:

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:

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:

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:

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: