saveenr: The Art of Writing Functional Specs (Part 3) – Spec Shapes

[Blog bot]

Источник: http://blogs.msdn.com/b/saveenr/arch...ec-shapes.aspx
==============

 

In Part 2 I mentioned that one way to harm to readability of a spec was to not understand the audience or what they need from the spec. Let’s expand on that.

Not all specs are the same, and different situations call for different approaches.  I can categorize these situations into some major buckets. A spec will have a particular “shape” for each situation that I will describe briefly.

 

 

INTEROPERABILITY SPECS

These are specs that describe Schemas, Languages, Formats, etc. The reason I use the word “Interoperability” is that the most important thing with these documents is that they are clear about what they define because these are used as reference material.

Even if you never write an interoperability spec, you will be a better spec writer by learning from them. Look at well known IETF RFCs (WebDAV for example: http://www.webdav.org/specs/rfc4918.html) and also read through this guidance.

 

Length. Generally reference specs are LONG. And because of that you can’t expect your audience to be capable of reading it in its entirety. It is for this reason, I recommend writing an a separate document to introduce the basics of the topic and like to your larger spec. It would not be surprising if these specs reach 100 pages. I written quite a few of that size.

 

The fundamental quality metric of an Interoperability Spec: Two people *NOT* on your team and using the document alone must be able to independently build components that work together.

 

 

API SPECS

These are specs that document things like the Windows CreatFile API (read the MSDN link there, it is a good example). Like interoperability specs, API specs will tend to be long and nobody reads them end-to-end, they just look up the section they need when the occasion calls for it. Follow the same guidance for Interoperability Specs, and you’ll be fine here.

 

 

 

USER EXPERIENCE SPECS

These include: Applications, Wizards, Forms, Views, Controls, etc. These are going to be heavy on mock-ups screenshots, of course.

Key points for these specs:

• Agree with your team on the scenarios first. If possible mock it up on a whiteboard first, before you write a single line in the spec.
• Keep the initial mock-ups very rough. You want feedback on workflow, not nitpicking the layout.
• As the UI gets built I usually update the spec with screenshots of the latest build – annotating them as necessary. When the code is about to “ship” I’ll update with the final screenshots.

Length: These tend to be heavy with screenshots and workflows so they tend to be long – but not as dense as the other specs.

Later in this series of blog posts I’ll try to show an example of a good UI spec.

Common things these specs should cover:

• Scenarios
• Consistency
• Workflow
• Entry Points
• How users experience errors
• Navigation model

SERVER SPECS

These are specs that deal with components that run on a server. These are the most difficult to write well. To do a good job on these you have a developer’s technical background and mentality. In my career at Microsoft I only met one person who despite never having written a line of code, did an amazing job of writing these specs.

The particular challenge of these specs you must thoroughly describe how components interact as a system and this requires knowing the deep technical details, and an incredibly solid grasp of distributed systems, operating systems, networking, memory management, security, paranoia, etc.

Let me give you a quick example of “server thinking” in a spec. Back in Dynamics AX, I designed a scheme to automatically size the columns in our SSRS reports – a feature SSRS does not have. I wrote part of the code which involved calling a GDI function called MeasureString (there are better alternatives available now, FYI) and gave it to the developer to integrate with his code. I also told him and added a line in the spec requiring that we called Dispose() as needed (being paranoid double-checked his code to verify this). In the spec I specifically required to test team to verify that we weren’t leaking GDI objects over long periods of time (weeks).

Length: Paradoxically perhaps, when done well, these spec don’t have to be very long at all – anywhere from 5- 15 pages .If they do get long, rethink how you are writing it.

 

PARTING THOUGHS

• There are other “shapes” as well. For example, we have “Service Specs” that deal with things that are online: a search engine for example.
• Am interested in your feedback: What are signs of good specs in the categories above? Let me know.

Источник: http://blogs.msdn.com/b/saveenr/arch...ec-shapes.aspx