RE: [VM] Structure of the Cookbook

Those all sound like good ideas to me.  (Though I'm not the one doing the editorial work they require!)

David Booth


> -----Original Message-----
> From: public-swbp-wg-request@w3.org 
> [mailto:public-swbp-wg-request@w3.org] On Behalf Of Thomas Baker
> Sent: Friday, March 17, 2006 6:49 AM
> To: SW Best Practices
> Subject: [VM] Structure of the Cookbook
> 
> 
> 
> On Fri, Mar 17, 2006 at 10:58:42AM +0100, Thomas Baker wrote:
> >    3) "Title of Section 3"
> >       Currently called "Some considerations when choosing a URI
> >       namespace".  David suggests: "Choosing a namespace URI: hash
> >       versus slash".
> ...
> >     8) Numbering of sections is requested.
> 
> The body of the paper,  with its unnumbered sections, is 
> currently structured as follows:
> 
>     Introduction
>     Apache configuration
>     URI Namespaces
>     Choosing a recipe
>     Content negotiation
>     Recipe 1
>       .
>     Recipe 6
>     Requirements [*]
> 
> On re-reading this document with some distance, I find the 
> above sequence of material somewhat confusing and would like 
> to propose a different sequence, with somewhat different 
> section headings:
> 
>     Introduction
> 1.  Requirements [a]
> 2.  Content negotiation
>     Apache configuration [b]
> 3.  URIs for vocabularies, properties and classes [c]
>     Vocabularies that use a 'hash namespace'
>     Vocabularies that use a 'slash namespace'
>     Vocabularies that use other types of namespace
>     Choosing a namespace URI: hash versus slash [d]
> 4.  The recipes
>     Choosing a recipe [e]
>     -- Simple configuration
>     -- Extended configuration
>     Recipe 1
>       .
>     Recipe 6
> 
> Comments
> 
> [a] The Requirements section is where the assumptions
>     underlying the whole document are articulated, and in
>     its current location at the end of the document these
>     assumptions are somewhat lost.  This section is not very
>     long -- it prints out at little more than one page.
>     I therefore propose we put it right after the Introduction.
> 
> [b] Having read in the Requirements that one should be able
>     to get an RDF description (at a minimum) or possibly also
>     "human-readable" documentation, the reader wonders how
>     this can be done.  The answer: "content negotiation".
>     The brief technical overview of Apache configuration for
>     Webmasters can follow here as a sub-section.
> 
> [c] David Booth suggested "s/URI namespace/namespace URI/", and
>     the recent thread on hash namespace URIs [1] has revealed a
>     need to clarify the use of "namespace" and "vocabulary".  I
>     suggest the slightly more verbose section title "URIs for 
>     vocabularies, properties and classes".
> 
> [d] As per David Booth's suggestion.
> 
> [e] The recipes themselves should be grouped into a section, and it
>     seems logical to use the text on "choosing a recipe" as the 
>     introduction to that section.
>     
> Tom
> 
> [1] 
> http://lists.w3.org/Archives/Public/public-swbp-wg/2006Feb/thr
ead.html#msg105

-- 
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 Friday, 17 March 2006 22:04:29 UTC