Re: dropping "title" column from specifications table?

On Sep 26, 2011, at 4:20 AM, Michael[tm] Smith wrote:

> Hi Peter,
> 
> I'm wondering if, in order to reduce confusion among maintainers of
> testsuites/specs in the test harness/framework, you'd consider dropping the
> "title" column from the "specifications" table in the DB schema.
> 
> To me at least, that column doesn't seem necessary. At least, the data from
> it is actually not used in the framework code itself anywhere except in the
> util/GenerateImplementationReport.php code -- and that code could easily be
> switched to use the "description" contents instead.
> 
> So, unless you need to use the "title" contents in the shepherd code, maybe
> you could consider dropping it and having the GenerateImplementationReport.php
> code use the "description" contents instead.
> 
> If you want further rationale, here are more details:
> 
> The context for this request is that, as I mentioned to you a couple of
> weeks back, I've been working on writing up a Web UI for some of the tasks
> that currently require direct access to the harness/framework mysql DB and
> shell access to the server the framework code is running one.
> 
> One of those tasks is the task of adding a new specification, which amounts
> to adding a new row to the "specifications" table in the DB. And among the
> columns in that table are "spec", "description", and "title".
> 
> As you know, the "spec" column stores a short (less than 32 chars) string
> that's used as the DB key for the spec (as well a shortname in framework
> URLs -- similar to the shortnames we have for specs in /TR working drafts).
> and the "description" column holds the full name of the spec. Example:
> "navigation-timing".
> 
> So that's all well and good. But then there's the "title" column which,
> like the "spec" column, stores a short (less than 32 char) string, and the
> semantics of which are "human readable short title for the spec". Example:
> "Navigation Timing".
> 
> I think that "title" column is problematic in that it's a potential source
> of confusion to testsuite/spec maintainers. The scenario I have it mind
> that a maintainer goes to the framework to add a new specification, and
> they are stumped with when trying to choose content for that "title"
> column: What I can imagine them thinking is, If it's not a shortname-like
> ID thing like the "spec" string (and not used in URLs), and it's not the
> full title of the spec, then... what is it, exactly?
> 
> To be more specific about why I think it would be confusing for them: I
> think for a lot of spec/testsuite maintainers, the full titles of their
> specs are already very short -- less than 32 chars -- e.g., "Navigation
> Timing". So, what those uses would likely end up doing is just repeating
> the "description" contents in the "title" column. And for other maintainers
> who have specs with full titles that are longer than 32 chars, I don't
> think it'll be clear to that what abbreviated version of the full title
> they should use, or why an abbreviated title is even needed to begin with.
> 
> So, while I think it would not a huge problem if you kept the "title" column,
> I think it would help prevent some user confusion if it were dropped.
> 
> 
>  --Mike
> 
> P.S., From looking at the harness code, I can see that must have written
> the "specifications" schema and the code for handling the specification
> data after you'd written the "testsuites" schema and the code for handling
> that, and maybe you initially created with the "specifications" schema with
> both "title" and "description" columns for symmetry with the "testsuites"
> schema -- where the distinction between the "title" and "description" of a
> testsuite is actually quite useful.
> 
> For example, "WOFF User Agent" (testsuite title) vs. "User agent tests for
> Web Open Font Format" (testsuite description). It's especially useful if
> you have multiple test suites for a particular spec, or multiple versions
> of a test suite, and you want to give testsuite maintainers a way to help
> users of the harness to be able to clearly distinguish among the different
> testsuites.
> 
> But while a description for a testsuite is something useful in the context
> of the harness, a similar description for a specification really isn't --
> because there's no similar need to multiple versions of a specification
> stored in the harness, and no need to distinguish among different
> specifications, because their titles alone are sufficient for that.
> 
> So I can see that what you ended up doing for the specifications case was
> taking the "description" column that you had for testsuites, and sort of
> repurposing it for the full spec title (instead of an actual description)
> -- which left the actual "title" column kind of hanging around without a
> clear need.
> 
> -- 
> Michael[tm] Smith
> http://people.w3.org/mike/+

Hi Mike,

For the CSS specs, many of them have a rather long formal title and a significantly shorter name that's commonly used for them, i.e.:
CSS 2.1: Cascading Style Sheets Level 2 Revision 1
CSS3 Images: CSS Image Values and Replaced Content Module Level 3
CSS Lists: CSS Lists and Counters Module Level 3

Using the 'spec' short name is not appropriate for general UI as it really is meant to be used, as you said, as a DB key and in URIs, and given the long formal titles of some specs, having a shorter name is very helpful in the UI.

I accept that for many specs the 'title' and 'description' fields will simply be identical.

If it helps, consider 'title' to be a version of the URL short name suitable for UI use. (Which is sometimes more of a change than a simple transform, like 'CSS-STYLE-ATTR': 'CSS Style Attributes'.)

While the harness doesn't make much use of the 'title' field, Shepherd does, as it has more exposure of the specs in the UI. I want both the 'specifications' and the 'sections' tables to be sharable between the tools. (In fact for a setup using both Shepherd and the harness it makes more sense to maintain the spec and section tables in Shepherd as that's the first point of exposure between tests and specs.)

So bottom line, I really think that field is necessary and it makes sense to keep it around. The pattern of a short name and full name is also used in other tables, like 'formats'.

Peter

Received on Monday, 26 September 2011 17:33:22 UTC