"Requirements Specification Documents" Are Essential!
(
Aug 24 2007 - 08:14:18 AM by
Timothy Khouri) - [
print blog
post]
Typically at my job each of the developers handle about three or four at a time. Because I work in the service industry, we never really "end" a project, but rather we just finish the major development and then continue to "support" our projects from here on out.
Due to the incredibly repetitive nature of our work, we've built a lot of tools that handle most of the work. This makes they typical job only about 20 to 40 hours of work. However, we also get our fair share of bigger clients whose projects demand more time. At that point, an RSD is essential!
I'm currently working on a project that I've scoped to be about 500 hours total architechture / development time, and the last three weeks have been dedicated to understanding and documenting the client's needs. Now that I'm taking my loose notes and compiling them in to a "Phase 1 RSD", I've started to do a few new things that I am finding very helpful.
Write A Story
Some people (including my boss) will argue that you should start off with a Microsoft Word RSD Template, and build your document with a Table of Contents, an Overview section and then move on from there. But I think that there is a better approach for your Phase 1 RSD document.
I'm writing out the spec in a sort of "story" fasion, and so far I'm really liking the way the document quickly teaches and explains the client's needs, and how the system being designed will fill all of those needs.
Don't get me wrong, I'm not talking about a "once upon a time", but rather the document sounds more like: "A manager will recieve his set of assignments that needs to be worked. He will log into the web interface, and choose the 'new assignments' section. Then, after filling out the contractor information..." etc.
Basically, if you memorized my RSD, you could give it as a presentation and people will simply assume that you have a complete grasp of the project.
Vocabulary Definition Links
As I am writing my "RSD Story", I would use terminology that I realize is not commonly known. So right away, I have a "Vocabulary" section at the bottom of my RSD, and every time I write a word (for the first time in the document) that is system or even client specific, I make a vocab entry and link to it in the Word document.
Just in the first two pages alone, I have about 25 links to new terms. This will help you and your client to be on the same page regarding words and terms that they may take for granted. Being on the same wave length with your client is key in agile programming.