Utility for software systems specifications
A Minispec is a tighly scoped description of a (small) chunk of the software. It is long-lived, precise and small.
I am not sure if the term is used by anybody else. I think Ed Yourdon has written something about that, but “Minispecs” with the desired semantics is simply a definition by me.
Role in the Big Picture
Any larger project has probably a main specification that serves for many stakeholders as the first information point to the project. But where to put the details? Details are very important and should often be specified not only in code. But putting too much details in high level documents isn’t right either. That’s where minispecs enter the scene.
A Minispec is not the same thing as having hierarchical specs. A Minispec is the last document before the raw system and it’s source code. Sometimes you must not even write he Minispec before the code, it’s also fine if you do it afterwards. Sometimes you write a minispec before coding and refine it after implementation. Remember it’s long lived and has not only value to understand what to implement but also to understand years later what a part does and why.
Example of a Minispec
In the Spec of Quality Spy you can find a Minispec of a Drag & Drop functionality. Drag & Drop implementation is really a detail of the program and I don’t think that any stakeholders except developers and testers are interested in any edge cases there. Nonetheless it’s not trivial, since there are multiple valid and invalid routes. So the spec will largely improve the understanding of this functionality and it’s constraints. And it’s short!
Basic Idea of Implementation in System Composer
Actually you need no special software to create a Minispec. You can do that fine with MS Word or also with WordPress as I showed with the Drag & Drop Minispec. So why do integrate this at all, beside linking it to the main system decomposition?
You usually only need a very small sub set of the word processing tool:
The whole idea of System Composer was not to create a “process” that you couldn’t implement without it. You can create the RichSpec (or however I will call that in the future) with MS Word. System Composer just makes it more explicit. The same should be true for Minispecs. System Composer will not allow you to create better Minispecs, it’s just that it has an explicit name here and that an applied pattern is a little more in software boundaries than before (but not too much, I hope!).
Let’s take a look at a wireframe:
We obviously need a list of specification documents where documents can be added and removed and sorted. Maybe it should be possible to group the specs into folders.
Note: Folders are yet to discuss, since System Composer works with nesting specs it must be clarified how this works. I think good design would be to also link the minispecs to the current .rspec file and allow to show either the minispecs on the current level or the Minispecs of all sub-.rspec files.
What I’m pretty sure about is how the spec should be edited. The Minispec should simply be a list of sections. And there are different section types. This should also be very flexible to add new section types in the future. It should be similiar to the WYSIWYG test protocol feature in Quality Spy.
Implementation in WPF
This section model should not be hard to implement in WPF when an ItemsControl is used and for every section type (or it’s View-Model) a DataTemplate is used.
Export and Publishing
System Composer is a tool for the author of specs, not the reader and this should also not change, so all Minispecs must be exported to something. What this something is another story. I think first priority should be PDF instead of MS Word, because a Minispec is a stand alone document. This can be clarified once the editor is set up and working. Since I currently investigate how to blog specs it would also be very cool to publish it somehow to WordPress.
Summary of new Feature
Let’s summarize the new feature of System Composer:
Things to be Done
Currently the idea hasn’t settled, but from the current perspective shuch things would need to be done:
From there on let’s see how it evolves.
It is all in the very beginning and many directions to head for, so feel free to discuss.