System Composer

Utility for software systems specifications

Minispecs

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:

  • Text with simple formatting, sometimes tables
  • Images for linking wireframes, data models and sometimes other images
  • A list of high level test cases

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:

Minispecs-Editor

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.

Entity Model

MinispecsModel

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:

Summary-Spec

Things to be Done

Currently the idea hasn’t settled, but from the current perspective shuch things would need to be done:

  • Adding, removing, deleting and enlisting Minispecs
  • Setting up the basic-editor with text sections first
  • Add some more sections (simple first) such as test spec section or images section
  • Create a first export format, preferrable PDF
  • Allow the linkage between Spec-“Functions” and Minispecs.

From there on let’s see how it evolves.

Discussion Welcome

It is all in the very beginning and many directions to head for, so feel free to discuss.

Advertisements

One comment on “Minispecs

  1. Pingback: Task-oriented UI (Redesign) | System Composer Specs

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Information

This entry was posted on September 21, 2013 by and tagged , .

Navigation

%d bloggers like this: