Those of you who have actually discovered the Registry and tried to add stuff to it have (I hope) already realized that we had Step-by-step Instructions for doing so. They were old, and we’d added new things (mostly Jon added new things—I just rant, nag and test), so I finally re-did the instructions. They can be found here: http://wiki.metadataregistry.org/Step-By-Step_Instruction.
Looking at the old instructions was, for me at least, a reminder that we have made progress, much as it sometimes seems like we’re moving at a glacial pace. The interface has changed, we’ve added versioning and history, as well as schema registration (read Jon’s posts for more details). There’s still lots more to come, and believe me we have seemingly endless list of what’s still missing. But writing documentation, even basic stuff like these instructions, is a humbling experience. Trying to do things more linearly than I usually do reminds me yet again where the gaps are.
One of the issues, which I’m not sure I’ve papered over very well in the instructions, is something I call the “eating our own dog food” problem. Those of you who know me personally have heard me use that phrase before—it’s a favorite. It basically means that, if you’re just preaching about how to do something, and not doing it, you’re not eating your own dog food. Not a good thing, and likely as not it will affect your credibility in ways that aren’t very comfortable, because SOMEBODY will call you on it.
Where we managed to step in it (the natural product created from said dog food, that is), was when we extended the registry from value vocabularies only to value vocabularies and schemas. Then, our model of concepts and properties of concepts started getting a little funky. When you’re registering schemas, you’ve got an aggregation of schema properties, and then, um, properties of properties? Uh oh. You can see the problem, I think—it’s about identifying and defining terms (among other things), and isn’t that what we’re supposed to be doing?
So, for the moment, until we’ve figured out how to hold our noses and eat that unappetizing dog food, we’re making a distinction in the schema instructions between “schema properties” and “specific properties.” Not elegant, but until inspiration strikes, somewhat helpful, I hope.
If any of you have occasion to use the instructions or stumble upon them and want to provide some helpful (or not) comments, just send them along to me: email@example.com.