Solved

design documents vs. requirement specifications

Posted on 2010-08-21
18
889 Views
Last Modified: 2013-11-26
im not a computer scientist.

but now i have to develop a plan to standardize SRSs and SDDs into our groups project management.  

 problem is, various groups within our org have historically been making these documents however they see fit.   some of them are really sparse and/or inconsistent.

I'm not sure i even fully understand what is the difference between the two.  where does one start and the other end?

0
Comment
Question by:rwj04
  • 7
  • 4
  • 4
  • +2
18 Comments
 
LVL 2

Assisted Solution

by:goducks
goducks earned 100 total points
ID: 33490908
At the start of the project these docs have different directions (forward/backward), but after the project is over they can be used in production support (sorry if you know all of this).

Requirements docs are "looking back" type of documents that spell out what the customer (your biz partner maybe - whoever the app is for) wants the thing to do.  Something like, "The application shall turn the screen white when button 'x' is pressed." is a requirement.  These are typically captured during elaboration sessions between your biz partners and your group's Systems Analysts (BSA's).  These documents typically end when those elaboration sessions end (unless you're using an Agile methodology, then it gets a little gray).

Design documents are "move forward" type of documents spelling out how the application is supposed to be made.  These are typically created from the requirements documents and take more on the form of use cases:  "The user presses button 'x'."  "The system changes the color of the screen to black."  "The system displays the new screen to the user."  These documents start after or even during elaboration sessions and last well into after construction has begun.  They typically are managed during the life of the project and even into a production support environment as applications tend to change as they're being developed.

Design documents are mostly what the application is supposed to look like (storyboards) and what it's supposed to do (use cases) as well as technically how it's supposed to do it (functional specifications).  In addition, a data dictionary is also generally used to describe the database makeup (fields, field data types, sizes, etc).

So, what's what?  I'll try to break it down as best as I've ever used it:

Software Requirements Specifications
- Requirement Items (list of user requirements)
- Roles & Actors Diagram

Software Design Documents
- Use Cases
- Storyboards
- Functional Specifications
- Technical Specifications
- Data Model (& Dictionary)

0
 
LVL 2

Expert Comment

by:goducks
ID: 33490911
Also, something to point out... our single group (among many) created several different document types and templates to handle the same thing... it ended up basically being a "who's template was used first" when we created our use cases and such.  I think it's typical to have that ambiguity, but if you can sort out standards - and get people to follow them - this doesn't have to be the case.
0
 
LVL 12

Assisted Solution

by:marklorenz
marklorenz earned 200 total points
ID: 33492233
You should look into UML. This is the de facto industry standard software development methodology. You want to capture your requirements (SRS) in use cases or user stories. You want to capture your design in class, sequence, and state diagrams. The requirements focus on WHAT, design on HOW.

Highly recommend getting consultant to mentor your team. Google these topics for articles and books. Best of luck.
0
 
LVL 5

Author Comment

by:rwj04
ID: 33492971
i agree that a consultant would be beneficial, but not sure that i could get management buy-in on funding one.

i would like a few recommendations on credible books and web articles, that have a how-to focus.    

i've googled it a bit, but its kind of overload and divergences, that i'd like someone more experienced to parse.
0
 
LVL 2

Expert Comment

by:goducks
ID: 33493442
What you're talking about is either having a consultant help you or you hire somebody to come in and do this for you.  You're not going to learn it from a link or a book unless you're talking about several links or several books.  What you're talking about is several years of experience.  I recommend you put together a proposal for your manager to bring somebody in to help through this, but if you don't have the budget then googling and taking some classes/attending some seminars is probably going to be your best bet when the funds aren't there.

I wish you luck.  What you're faced with is not an easy answer.
0
 
LVL 7

Assisted Solution

by:JimBeveridge
JimBeveridge earned 100 total points
ID: 33493553
It sounds like you have a lack of requirements for your project. What's the primary goal? Get everyone to use the same fonts and margins? Pass an ISO audit? Reduce production costs? Make it easier for the tech writers?

What's your budget and timeframe to get this done? Do you have buy-in (or control) over the other managers for the other groups? What is the criteria for "accepting" your work product?

This is a change management case study. The technical problems you face are dramatically smaller than the political and management problems in getting groups to agree and to change. You may need to "sell" your solution on a manager-by-manager basis.

Once you are "done" with your work, who will enforce the standard? Who will review documents for compliance? Will they have the authority to enforce anything? Are there penalties for not following the standard? Having written many of these documents in my time, I utterly ignored anyone who tried to change what I was doing unless they had senior management buy-in, penalties for failure to comply, and budget to follow-through on what they were doing. And even then I'd ignore them if I was in a stronger political position than they were.  This sounds cynical and anti-social, but when you've lived long enough with the "manager of the quarter" trying to make their mark, the whole exercise was almost always a waste of time. (To be fair, I'm also an internationally known writer, so I almost always had better writing credentials than the other person.)

The fact that you are approaching this without the benefit of having written these documents yourself is going to make this a very challenging task.

The problem with consultants is that they often have a "one size fits all" approach. You think you are hiring a consultant to help you manage your documentation. In far too many cases, after you've blown your budget, you discover that the consultant is really trying to reengineer your organization's work methodology, demonstrating the value of his solution with beautiful PowerPoint presentations, cost savings diagrams, modern methodologies case studies, blah blah blah.

In other words, hiring and managing a consultant is itself an art. If you haven't done such a thing before, you are more likely to get burned learning how to do that.

My recommendation - find the people in the company who excel at producing these documents. These people should generate the documents effortlessly and be the envy of everyone else trying to write them. Get those people in a room to figure out how to do incremental change instead of revolutionary change. During that process, have a few people "test" the proposals to see if they work.

However, as soon as you publish your reference documents, you will discover that everyone who uses them has a completely different perspective on what you thought you said and they will do things in a completely contrary way (or will be so confused that they will do nothing unless you babysit them.) You will have to write documentation about documentation, and you will have to have reviewers who all agree on how these documents should be done who proof read, edit, and teach the documenting techniques.

I started this off by asking if you just wanted to get everyone to use the same fonts and margins. You probably thought I was joking, but I wasn't. If you don't have an entire system in place for education, review, enforcement, and continual improvement, then the fonts and the margins (and maybe the cover page) are about the best you are going to do. Unless you have both Macs and PCs, in which case forget about the fonts and just standardize the margins.

I agree with goducks. Good Luck. In a Dilbert comic your project would have a cloud of doom over it. Personally, I'd find a convenient excuse to shelve the project and move on.
0
 
LVL 5

Author Comment

by:rwj04
ID: 33493560
^ right.  i agree with you completely.    we're already having difficulting getting our project funded at a minimal level.    we can make a case for additional consulting fees, but this is not a priority at the executive level.

so in the meantime, I'm asking you, the experts, to suggest a few recommendations on credible books and web articles, that have a how-to focus.    
i could google it myself, but i have no way to judge what is credible.  
0
 
LVL 7

Expert Comment

by:JimBeveridge
ID: 33493597
It's an impossible question to answer. Is the project one person? Ten people? 500 people? The scale and scope of required documentation varies wildly. Do you have offshore outsourcing? Is your orgnization using any existing models (UML, etc.)? Is your organization sophisticated enough to do use case analysis? The books would need to account for that. Is it a medical, financial, or DOD? Then you have legal requirements. Are you using (insert your favorite programming methodoloy)? Then follow the rules for that.

The very fact that you are asking about all of these documents implies that you are using waterfall development. If you have any groups using Agile techniques, then your solution is going to be hopelessly inappropriate.

I've written these documents using templates from several companies. None of the documents in any of those companies were remotely similar to each other - and those companies were all in the same industry and all had similar project sizes. You can get skeletons of those documents from the Software Engineering Institute (SEI). And you'll lose a fortune trying to use them unless you have the expertise to know which parts your organization really needs.
0
 
LVL 5

Author Comment

by:rwj04
ID: 33493607
okay, my previous post ^ was addressed to goducks ^^^, i didnt see your post ^^ until after I posted ^

the project itself is a technical project of very large scope, architecting and developing an entirely new manufacturing test system.    the largest of it's scope in our group in over a decade.   but we're not software engineers or computer scientists, were a handful of EEs and our department hasn't ever addressed the SRSs or the SDDs in any meaningful way in the past.      

the problem is, our company's various product designers have their own SRSs and SDDs all over the map, and are not exactly how we want to model our new protocols after.

im going to consult with SW engineers in product design, but i want to have a good idea of how SRSs and SDDs *should* be done so I can at a minimum ask intelligent questions.

so, we're not going to hire consultants, and were not going to hire SW developers as  contractors or team members.   its not up to me, but i know who it is up to, and it isnt going  to happen.    as  Rumsfeld infamously said, "you don't go to war with the army you want, you go to war with the army you have"
0
Do You Know the 4 Main Threat Actor Types?

Do you know the main threat actor types? Most attackers fall into one of four categories, each with their own favored tactics, techniques, and procedures.

 
LVL 5

Author Comment

by:rwj04
ID: 33493609
daggonit, we need an EDIT button.  every time  I post, someone posts before i submit, messing up my intended carat references (^).    add one carat to each of my previous references.

or dont.

i need to stop using carats.


0
 
LVL 12

Assisted Solution

by:marklorenz
marklorenz earned 200 total points
ID: 33495764
I'm on my phone now, but books: UML Distilled by Fowler and Craig Larman's books are recommended.
0
 
LVL 12

Expert Comment

by:marklorenz
ID: 33495920
I'm on my phone now, but books: UML Distilled by Fowler and Craig Larman's books are recommended.
0
 
LVL 2

Expert Comment

by:goducks
ID: 33497856
Keep in mind that UML isn't necessarily the only method to use.  Each situation is different.  If you want to read up on UML though then marklorenz gave you a starting point.  However, you do need to know that UML is only one method.  The Rational methodology (now owned by IBM) uses UML exclusively and even has a good toolset to use, but it's only one of many methodologies.  Personally, I'm familiar with UML and can see how it's usable in most Waterfall development situations, but if you're adopting an Agile or XP approach (most common these days) then UML is not the way to go.  Proceed with caution.
0
 
LVL 5

Author Comment

by:rwj04
ID: 33508025
we're not especially agile.

i'd say we're sort of trailing edge.


0
 
LVL 12

Assisted Solution

by:marklorenz
marklorenz earned 200 total points
ID: 33510710
Agile is something you can ease into.  E.g. Do longer iterations (say 4-5 weeks) and use use cases instead of user stories (which means more documentation - less agile, but still a move in that direction). Use cases can be written in MS Word or whatever other editor you like.  Here's an example template: http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.23.2552&rep=rep1&type=pdf

UML is not rocket science - it is just a standard, well-understood way of developing and communicating designs.  There are a lot of online tutorials, articles, ... as well as good books (as I mentioned previously). E.g. try objectmentor's site (such as http://www.objectmentor.com/resources/articles/umlClassDiagrams.pdf).  You can use Visio or another drawing program for smaller projects.  Bigger ones you will want ArgoUML (free) or EA (commercial).

As I stated before, UML and use cases are de facto industry standards, so you will have lots of resources and personnel to pick from.  Going another route will be a different story.  As for consultants, there are many good companies out there (I have no vested interest in any of them), including GearStream (http://www.gearstream.com/) and Instantiations (which is now part of Google).

Best of luck! Mark
0
 
LVL 16

Accepted Solution

by:
theo kouwenhoven earned 100 total points
ID: 33539933
Hi rjw04,

a requirement specifications is a document that is also known as user requirement specifications, so its logical that the user(s) will create this (together with 1 IM/IT person if required, to support). This user(s) can also support the rest of the project.
The URS will be the non technical instruction for IM/IT to create design documents like System requirement specs (SRS), DB Design Document (DBDD), Program requiremnet specs (PRS), Validation Protocol (VP), Validation Report (VR)
And more if required.

URS
contains all information about the user requirements with respect to the new developement in clear non technical language.

SRS
Contains a high level overview with technical instructions and remarks, so that the user can read it and the designer can not misunderstand it.

DBDD
Contains a high level overview with technical instructions and remarks about the DB requirements. This document will be written by the designer, so that the user can read it and the DB manager or programmer can not misunderstand it. Can later be adopted by the DB Administrator or programmer to make a detail instruction for the required changes.

PRS
Contains a 100% technical description, so that the designer can read it and the programmer can not misunderstand it.

VP
Contains a detailed description point by point what to test, how and who. Normally the user(group) that created the URS is the person who have to test, but some processes (batch e.g.) are only to test by IM/IT.

VR
Contains the result of the executed validation report detailed per point and attached samples of the result.

If required this VR can be used to let the user sign for acceptance. It's not bad to let the user, designer and later the programmer sign for every document. the moment you let someone singn you make him aware that they are responsible for that part and they will really read the document.

Regard,
Murph
0
 
LVL 5

Author Comment

by:rwj04
ID: 33620705
we have similar breakdownd, though not entirely the same.  for my purposes, in manufacturing, we have a pretty well defined and standardized set of documents that i deal with

PRS: Product Requirement Specifications
MTS: Manufacturing Test Specification



within the manufacturing test arena, we currently  have a very ill-defined set of documents to describe how the software part of the test systems are developed:

SRS: Software Requirement Specification
 SDD: Software Design Document



then of course, we have the validation documentation

Validation Protocol
Validation Plan
Validation Report



my problem is the SRS/SDD division.   there's just no real consistency or standards within our org.



0
 
LVL 5

Author Closing Comment

by:rwj04
ID: 34031184
thanks, all
0

Featured Post

How your wiki can always stay up-to-date

Quip doubles as a “living” wiki and a project management tool that evolves with your organization. As you finish projects in Quip, the work remains, easily accessible to all team members, new and old.
- Increase transparency
- Onboard new hires faster
- Access from mobile/offline

Join & Write a Comment

Suggested Solutions

Title # Comments Views Activity
Scrum Planning 2 163
C# Design Patterns 2 85
factorial example challenge 10 61
object oriented javascript web form 8 71
Software development teams often use in-memory caches to improve performance. They want to speed up access to, or reduce load on, a backing store (database, file system, etc.) by keeping some or all of the data in memory.   You should implement a …
Introduction Many of the most common information processing tasks require sorting data sets.  For example, you may want to find the largest or smallest value in a collection.  Or you may want to order the data set in numeric or alphabetical order. …
In this seventh video of the Xpdf series, we discuss and demonstrate the PDFfonts utility, which lists all the fonts used in a PDF file. It does this via a command line interface, making it suitable for use in programs, scripts, batch files — any pl…
You have products, that come in variants and want to set different prices for them? Watch this micro tutorial that describes how to configure prices for Magento super attributes. Assigning simple products to configurable: We assigned simple products…

706 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question

Need Help in Real-Time?

Connect with top rated Experts

12 Experts available now in Live!

Get 1:1 Help Now