[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/thread.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 11:48:46 UTC