I've posted the first draft of the Durham specification. This spec is the central vision for Durham to help get people on the same page.

Since Durham is a developer API the specification is written from the developer's perspective and is not a typical informal spec that might be written for an end user application like AudioMan. At the same time I think the philosophy of the spec should be to explain what Durham is going to do, not necessarily how it will do it. In that sense the spec will stay simple.

The spec is written purposely in a very Joel on Software type of way. It's informal, it has diagrams and is in a single skinny column in a large font.

How it looks is actually quite important because it indirectly encourages brevity. An informal spec like this should be complete but not overly verbose and it should be balanced on the vague/specific scale -- too specific and it will go stale faster but if it's too vague it's not useful enough to go by. Spec writing is a skill that's going to take a lot of practise!

This is a first draft. The features of Durham are not locked down and I definitely welcome feedback. This is your chance to stretch your software engineering legs and show people how smart you are. :)

What kinds of things does an application writer using Durham (like AudioMan) need? What kinds of things does a metadata type plugin (like id3v2 for MP3, or Microsoft Word DOC, or JPEG...) writer need? What kinds of things does a local cache plugin (like hooks to a MySQL or hsqldb database) writer need? What types of security problems could Durham have with files?

Durham will be pulled in all directions by these concerns. It doesn't hurt to think ahead a bit and get everything together in one place.