- SPEC就是项目干系人之间的项目契约
- 写SPEC之前需要先了解读者的能力,读者如何使用这份SPEC,以及他们希望从SPEC中获取什么信息
- 注意SPEC的使用场景
The Art of Writing Functional Specs
by Saveen Reddy (http://blogs.msdn.com/b/saveenr/)
Part 0:
In 16 years I’ve written an a lot of functional specs.
· I’ve written them in small teams and in big teams and every size in between.
· These specs covered many areas: email protocols, server components, user experiences, networking, graphics, telephony, image processing, printing, scanning, real-time communication, security, formats and encodings, APIs, object models, and many more,
· They range from specs with low-level code details (sometimes actual code) to high-level architecture, vision, and strategy.
· My specs have been featured as part of Microsoft’s training on how to write good specs.
And I always get the same feedback from those who read my spec:
“It was easy to understand your spec.”
They also usually ask me why I don’t follow the team’s spec template. 🙂 But we’ll cover that topic eventually.
These days I don’t write specs often – though I do still do a lot of writing – but wanted to share what I learned over those 16 years. I think it applies to anyone who needs to communicate with a technical audience.
So, today I’m starting a series of small blog posts called “The Art of Writing Functional Specs”. I’m not sure how many posts it will take. Let’s say 10 for now. I plan on writing a small post every day for the next 10 days. I hope you’ll enjoy this journey.
We’ll start in earnest tomorrow with Step 1: “What is a Functional Specification?”
FYI: I’ll just be calling them “specs” for most of this series instead of “Functional Specifications”
Part1: What is a Functional Specification?
It’s tempting to say a functional specification is a document that … blah blah blah requirements, scenarios, glossary. design details, etc. It’s tempting to say that because it is true – true but it misses the bigger picture.
A spec, yes, physically is an artifact – a document. You’ve seen quite a few of them, perhaps. But, what a spec really is something different. It is a representation of the binding agreement between program management, developers, testers, designers, product management, etc. It is the statement made by the team as a whole: “This is what we agree on; what we believe the feature is.” The spec is an outcome of a long series of collaborative events between many parties. It represents a deliberate, intentional decision by the participants that clearly defines what they are building and why.
NOTES
Do you need to write a spec? Here’s a great way to fail at it. Go lock yourself in room. Come up with a great idea and write it down to whatever level of detail you want. Then tell your team: “this is what we are building.” That will go over really well.
Part2: The Most Important Thing About A Spec
I tried thinking of all techniques I have seen or have used in making great specs. I put all those techniques in a crucible and boiled away everything until only one principle remained. Here it is:
“Specs must be readable”
That’s it.
And as obvious and trivial as it seems, that central message gets lost.
Why is it critical? Because if your audience can’t successfully go through the document and understand what is written, any design or discussion that stem from that spec is nonsense – the participants aren’t even on the same page to have a meaningful discourse.
So how do otherwise well-meaning and intelligent people sabotage their specs. Here’s a list:
· Too many words
· Underestimating the audiences ability to misunderstand
· Confusing spec writing with the writing of fine literature or a research papers
· Not understanding how their audience uses a spec or what they need from a spec.
· Using text when a table or list or a diagram would be much better choices
· Poor ability to structure ideas on the page or in their own mind. If the author is confused, what hope do the readers have?
Part3: Spec Shapes
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.