Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Typically we follow an Agile development process that tends not to put an emphasis on writing requirements and technical documents that nobody will read. We tend to focus our limited manpower to development and testing activities with collaborative design and whiteboarding as a key focus.

There is a mostly standalone web component that will take quite a few weeks to develop, but this work can be mostly parallel with other project work going on. To try and catch up time I was given a budget for hiring a developer on oDesk to complete this work.

While my team isn't accustomed to working off of a firm SRS document, I realize that with outsourced development that it is a good idea to be as firm and specific as possible so I realize that I need to provide a detailed Requirements and Technical Specification document for this work to be done correctly.

When I do write a Requirements document I typically utilize the standard IEEE SRS document template but I think this is too verbose and probably overkill for what I need to communicate to a developer. Is there another requirements document that is more lightweight and also accepted by a major standards organization like the IEEE?

Further, as what will be developed as a software module that will interact with other software modules, my requirements really need to delve into technical specifications for things to work correctly. In this scenario does it make sense to merge technical and requirements specifications into a single document, and if not, what is a viable alternative?

share|improve this question
    
"...I realize that with outsourced development that it is a good idea to be as firm and specific as possible..." interesting that you seem to hold a double standard to the way your team works vs. an external company. In this scenario, wouldn't your team fill the "customer" role? –  Michael Jan 2 '13 at 16:02
    
@Michael Well the reason for the double standard is two fold. One, I trust my own and my teams abilities to create solutions. Two, my general experience working with outside contractors has been predominately negative when they are faced with little direction and few requirements. The onshore team always has more ability to trap management into a corner and ruthlessly poke and prod them until they force said manager or stakeholder to make a decision :) –  maple_shaft Jan 4 '13 at 12:07
add comment

2 Answers

up vote 5 down vote accepted

The best option is probably to take an existing template or two (for purchase - also found in the appendices of Software Requirements) or three and tailor them. Remove sections that are irrelevant to your needs or add new sections that you like from one template into the rest of another template. Merge sections together if that makes sense. When combined, these would probably cover every possible type of question that might be asked, it's just a matter of filling in the details where they are needed.

Tailoring would make it not match templates by major standards organizations, but tailoring is a key component of process improvement and deployment programs. I don't think that anyone would have a problem with a tailored template, in most cases. To me, the explicit removal of sections makes for a nicer and more reader-friendly document than text that says "does not apply".

As far as providing specifications, I'd be hesitant on what is provided. If you will be providing inputs in a specified format, provide that format. If another system will be consuming outputs, provide the expected output format. These could be railroad diagrams, XML schemas, byte layout maps, and any sample inputs/outputs (sanitized, if necessary). If you're specifying something that needs to be a drop-in replacement for another system, specifying the public interface may be necessary as well. However, I'd recommend leaving as much leeway to the developer as possible to design and build a system around your requirements.

In my experiences, there's often a separation of the requirements of the system and a detailed description of the interfaces between components. I don't think this is always necessary, though. Conformance to a specified interface is, technically, a communication or environment requirement ("the system shall provide output in XML that conforms to the schema defined in schema file"). Separating the two is probably more appropriate when describing a system of related components rather than a single component, where I'd argue that having a single, comprehensive resource for what I'm expected to produce is better.

I'd recommend approaching this as defining only what you need from this system, leaving as much as possible up to the developer. If you spend too much time doing the specification such that there's only one or two solutions, then you've done most of the time intensive work (in my experience). As a developer yourself, you probably know what questions you might ask if you were presented with the general scope of the system you want - answer those as clearly and specifically as possible and hope the developer will ask any other questions you might not have thought of.

share|improve this answer
    
The IEEE templates were intended to be tailored. The problem is that it is entirely possible to tailor them to the point that the resulting document is worthless. The one time I looked, I saw no guidance at all about which sections should be tailored and which should not. Compare with the DOD-STD-2167A DIDs, that almost did not allow for tailoring, and for which it is immediately obvious that every section is there because it NEEDS to be there. –  John R. Strohm Dec 15 '12 at 16:32
add comment

Summary

If it is Agile, there is a couple of issues to consider. Firstly, SRS is a no-go in Agile, and secondly, the IEEE won't back it up by any standards as they don't apply here.

User Stories, not SRS

The best option would be to reconsider the methodology to something like RUP, or to practice Agile properly and benefit from its native solutions to problems, i.e. in agile, requirements are specified as User Stories.

Agile Methodologies

Consider Scrum, for example. All stories are first piled up in Product Backlog. Then, the Product Owner (you) select stories that should be implemented in the next sprint by putting them into Sprint Backlog. Finally, the iteration starts and you can watch the Burndown chart to see how stories are being implemented.

Another recommended Agile methodology is TDD or BDD where it is refined. The developer first writes tests based upon user stories and then codes the actual internals of the software to pass the tests.

Similarly, there is Extreme Programming, Crystal, DSDM and other agile methodologies to consider.

Software Process

When practicing Agile, or any other methodology, it is imperative that the particular methodology is chosen well and followed with a certain rigor. Otherwise, "we are using Agile" becomes "we are using a process which is not formally recognized and we are actually not even sure of the outcome, we don't know what we are doing, but let's already start hacking stuff"

share|improve this answer
1  
I don't recall reading anything about user stories in the Agile Manifesto... be careful not to confuse common agile practices with what you must do to "do agile." Being agile is about promoting practices that allow change and maximizing value. In an outsourcing scenario such as this, sometimes extra structure can create greater opportunities for agility. –  Michael Jan 2 '13 at 4:23
    
@Michael Agile Manifesto is not a software methodology. It is...a manifesto. FYI Agile methodologies existed long before this manifesto was written. Be careful not to confuse thinking how agile you are when, in fact, you are not following any formal methodology. You are just hacking stuff. That's not Agile. –  user42242 Jan 2 '13 at 12:18
    
we're in total agreement on that point. No process is... no process no matter what label you put on it. The main problem I have with your answer is in the idea that "SRS is a no-go in Agile" and "in agile, requirements are specified as User Stories." You can still be perfectly Agile and not use user stories. This is wrong and distracting an otherwise good answer. –  Michael Jan 2 '13 at 16:01
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.