dropping "title" column from specifications table?

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/+

Received on Monday, 26 September 2011 11:20:26 UTC