design documents vs. requirement specifications

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?

Who is Participating?
I wear a lot of hats...

"The solutions and answers provided on Experts Exchange have been extremely helpful to me over the last few years. I wear a lot of hats - Developer, Database Administrator, Help Desk, etc., so I know a lot of things but not a lot about one thing. Experts Exchange gives me answers from people who do know a lot about one thing, in a easy to use platform." -Todd S.

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)

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.
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.
Exploring SharePoint 2016

Explore SharePoint 2016, the web-based, collaborative platform that integrates with Microsoft Office to provide intranets, secure document management, and collaboration so you can develop your online and offline capabilities.

rwj04Author Commented:
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.
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.
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.
rwj04Author Commented:
^ 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.  
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.
rwj04Author Commented:
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"
rwj04Author Commented:
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.

I'm on my phone now, but books: UML Distilled by Fowler and Craig Larman's books are recommended.
I'm on my phone now, but books: UML Distilled by Fowler and Craig Larman's books are recommended.
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.
rwj04Author Commented:
we're not especially agile.

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

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:

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  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 ( and Instantiations (which is now part of Google).

Best of luck! Mark
Theo KouwenhovenApplication ConsultantCommented:
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.

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

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

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.

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

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.

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.


Experts Exchange Solution brought to you by

Your issues matter to us.

Facing a tech roadblock? Get the help and guidance you need from experienced professionals who care. Ask your question anytime, anywhere, with no hassle.

Start your 7-day free trial
rwj04Author Commented:
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.

rwj04Author Commented:
thanks, all
It's more than this solution.Get answers and train to solve all your tech problems - anytime, anywhere.Try it for free Edge Out The Competitionfor your dream job with proven skills and certifications.Get started today Stand Outas the employee with proven skills.Start learning today for free Move Your Career Forwardwith certification training in the latest technologies.Start your trial today
Project Management

From novice to tech pro — start learning today.