Hello,

as a good practice I recently started to built a functional requirements document for the software project I will begin to develop shortly. However, I've never done this before, so my question to you guys: could you give some directions?

I've already read some small parts of books on this topic, but I found that they were all too strict and formal. I don't know if following a less strict structure will lead to a bad document, so if it does, please say so (althought, I don't think this is the case).

I've started with a title page which includes a "last updated" field. Then I have a TOC with a sort of a disclaimer. Next I have an Overview which tells what the application is and what it must do (all in easy "chunks"). This page also includes an overview diagram (Visio Enterprise Application Diagram). Then I would like to go deeper in the functionality. Every "chunk" of what the app must do (it's jobs) has a description and if possible a flow diagram (do you think that is good practice?). I am wondering if it is wise to go more technical here, as in, "This job will occur in a seperate thread"? (notice the word thread) Or is better to talk only what it must do so that non-programmers will understand it too? The same question goes for the use of IT words such as "The server application will then e-mail using Exchange Server". And finally, is it wise to go into detail if the job is "Managing a 'keep-alive' status"? (I don't know how to do that without talking in programming slang).

If you have any other good practices please lett me know if you like,

Thank you in advance,

Michel van den Berg

(recovering from a freak accident just now. I had everything typed out and somehow closed out the window)

Anyway, there are a lot of great software related document templates here http://www.processimpact.com/goodies.shtml . I think those will help you out a lot.

Also, Requirements Development by Karl Wiegers is a great book! On Amazon

Regarding the information in your requirements document, you should ALWAYS dive deep enough into the details to determine how much a software product/feature is going to cost, but you don't always need to show that information to the end customer. If you're just trying to sell an idea to someone, they don't need the details. If it's a new system, you'll probably just want to show major features, assumptions, business requirements etc... If, however, you're in the code construction phase of a project, you'll definitely want to go into greater detail. It's all about deciding what level of abstraction the end user needs to see.

Check out Joels three parter. Very simple an practical guide to functional specs. Here is the link to part 1.

http://joelonsoftware.com/articles/fog0000000036.html

BOb

alexdresko wrote:

Anyway, there are a lot of great software related document templates here http://www.processimpact.com/goodies.shtml. I think those will help you out a lot.

For some reason the . has been included in the url so when you click you get a 404. For clickety purposes the url is http://www.processimpact.com/goodies.shtml

netclectic wrote:

alexdresko wrote:

Anyway, there are a lot of great software related document templates here http://www.processimpact.com/goodies.shtml. I think those will help you out a lot.

For some reason the . has been included in the url so when you click you get a 404. For clickety purposes the url is http://www.processimpact.com/goodies.shtml

Yeah, my regexp isn't that clever to not include a . if a space follows the .

Thnx for that link! Thought, I'm still wondering what exactly belongs to my spec. Currently, I've created some little diagrams. Altought, having never done such thing, I don't know if this is how it should be done. Could someone give a little peek? The overview diagram is here: http://www.xs4all.nl/~max2els/overviewdiagram.pdf

What do think of this little diagram?

What I'm doing next is writing down the features for the server and the client application, as in:

2 - Server Application Features

2.1 - Processing new lists
- Full discription for this feature (= text) + small notes (technical and so)
- A (basic) flowchart of this feature

2.2 - etc

So... do you think doing this is ok? Also... What do you think about inserting busniness rules somewhere in this document.

I remember when I first starting writing this kind of documentation. It freakin scared me! I didn't know what to do or what it should look like. I didn't know how to get started or where to turn to for help.

At first you think, "Surely there's a common, well defined way of doing this." But in truth, there is no "right way" or standard. Realizing that only makes things worse I think. Even the 3rd party software offerings out there are out of my pricing range.

The way I got to where I am now is by starting small. It doesn't make sense to implement a full scale process your first time out. You'll end up with 10,000 pages of stuff you can't keep up with or maintain.

You should only do enough to help you get through the project (and to cover your ass). Beware of "Paralisis by analysis".

Regarding business rules, yes, I think they're very important. It shows that you have a firm unstanding of your customer's business. I don't outline my customers' business rules for every project I do though. Sometimes it's just overkill.

The Process Impact templates are great if you check them out. There's already a title page, table of contents, revision section, header/footer, business rules section, etc...

I just went through this for a big project, and it was my first go. I found a lot of the existing literature on what to do and how to format stuff to be inconsistent and confusing.

Here's what I did:

I desribed briefly a high-level view of the business model.

I diagrammed a logical or domain model (used Enterprise Architect, but any UML tool is good for this). Confusion point #1 what is difference between "logical" and "domain" models? Got me. They are both basically high-level class diagrams really.

I was going to write the use cases, but got lucky and someone at the client who was most knowledgable about the current process wrote them, all I had to do was edit them.

Class diagrams - don't see the point. It's impossible to design all your classes up front! So the domain model (see above) is about as far as you're going to go on that, IMHO.

Logical data model (or just "data model" - not even sure why "logical" is here). This is your classic ERD, so it's where I felt most at home. Enterprise Architect does pretty nifty ERDs, so I scripted the database, like I always do (and more people should be doing), and reverse-engineered to create those. Personally I think one diagram is too confusing for a large database, so I break it up into smaller, easer-to-read diagrams.

Functional requirements. OH MY GOD! This is where I really struggled. I ended up putting things that are really part of the data dictionary (ok, you could do a data dictionary before the actual data model if you wanted). I haven't seen a good explanation yet of what to put for functional requirements. Thing is, your use cases tell you how the software should behave to the user. Your domain model (and data dictionary, if you did one) pretty much uncovers all the information you're supposed to capture. So I really couldn't figure out if functional requirements are supposed to be derived from use cases, and what material they should contain and how best formatted.

Funny thing is, I was real unhappy with my final product, but other people looked at it and marveled at it.

I would love to hear what other folks have to say about this.

Jim

JimFoye wrote:

I would love to hear what other folks have to say about this.

Jim

I do well on the higher level stuff, but my docs start to get unorganized once I start getting more detailed.

I start new projects with use cases (Word template) and a data dictionary (Excel template) Once those are in place, I move on to the high level requirements spec (Word again).

Throughout most of the design process I use MindManager X5 (plus the "6 hats" method) to think through things. I find I'm able to completely free my mind of all stored up thoughts related to a project this way. The documents I produce are merely formatted versions of the information I come up with in my mind maps.

If necessary, I'll produce an ERD, but only if the customer has some clue about what the data should look like. Otherwise, I'll dive right into Enterprise Manager.

I don't do class diagrams often either, as this type of documentation tends to go stale VERY quickly. It's very useful though when you're working with a set of domain objects that work closely together or when mixing design patterns. If an algorythm seems tought, I'll create a sequence and/or state diagram, but my UML is shoddy at best.

I develop my specs detailed enough to know where the highest risk areas area.

I generally use a combination of risk and feature based development (with a pinch of bottom/up and top/down).

From that information you can probably get a pretty good idea of the size of my typical project. I go into a lot more detail in my personal side projects because I don't usually have time to mess up.

<duplicate post>

This is long, so bare with me here. As a product manager, I have written several of these types of documents, so much so that I've got templates for around 100 or so different docs, everything from release requirements, functional specifications, all the way through end-of life-documents. I'm currently writing an application (using llblgenPro of course) to help manage this process. Hopefully the app will include a set of templates for each of these documents as a starting point that you can customize for your needs. That being said. Here's a summary of what I belive a functional specification should include: (As always, you need to customize this for your needs)

Basically, the functional specification describes what a specific feature will do, focusing on how the user will interact with the feature. It describes the guts of the feature and is a primary communication vehicle with engineering. It should be fairly detailed.

Here's what I put into a functional specification (general outline):

1. Feature Overview
2. Feature Description
   • Must Haves
   • Should Haves
   • Nice to Haves
3. User Scenarios
4. Prototype Example(UI)
5. Other considerations (platform, lanaguage, etc)
6. Dependencies (as it relates to other components, projects, etc that this piece of functionality depends on)
7. risks, assumptions

Each feature can have its own functional specification, however I've worked at various companies which tend to lump multiple functional specifications (ie multiple features) into a single document. It's purely up to you.

However there are several documents I typically write (or I'm involved in writting) prior to writting one of these. For example (Release Requirements, architectual specification, prototype docs, etc)

One of the first is a relase requriements document which describes the features and capabilities in a given release based on the customer needs. It is generally based on another document I use called market requirements document (Mostly I use this primarily when a new product idea is being presented, what's the market opportunity, justification, and so forth) which provides the business justification for the release. I use it as a high level document without drilling down into the nuts and bolts, that's what the functional specification and the architectural specfication are for.

Here's a sample outline I use for a release requirements document(general outline):

Executive Product Overview Itemized Features (Note: I use the functional specification to drill down into specifics for each feature) Must have: required features Should have: highly desirable features Could have: nice to have features System requirements Platforms Compatibility usability Performance Reliability Scalability Globalization Third party requirements Upgrade and migration Packaging Installation Obsolescence Documentation Support Schedule Risks and issues

I have other outlines if you want to see, just let me know. One thing to note is I come from the product management side and I tend to try and write (with the help of others) these docs upfront as much as I can. I must say, that there are so many different types of documents that you have to choose what works for you and when. Meaning, I've worked at some companies that create only 4-5 of these types of documents where at other companies (HP) we created many (20-30 docs of this type) It's a balancing act. Figure out what works for you as there is no right or wrong way of doing this type of planning upfront.

JimFoye wrote:

I would love to hear what other folks have to say about this.

Jim

Jim,

Being a Lead / Project Manager on a team you really have to do alot more documentation than a single developer would do. To me there are three basic audiences for the artifacts of a software development project...

1. Non-technical / End User / QA / Doc / Etc.

These are usually documents that describes what the application will do.

First you need to start with a list of requirements. Usually you focus on Functional or User or Domain type items. You can also have non-functional requirements like platforms, performance, number of users, etc. The list generally starts out general, then gets more granular. You might start out with:

Calculate Payroll Checks for employees

Which gets refined as you drill down:

Pay an employee a fixed number of Regular Hours Pay an employee a variable number of Overtime Hours Etc.

Once you have the requirements you usually come up with some document that describes how these requirements would be implemented/presented. This is all done in a non-tech/end user way. I call these documents functional specs. However, Functional Specs, Use Cases, Stories, etc are all the same things. Usually they are feature specific. Don’t make a common mistake though. A Use Case Diagram is NOT a Use Case. A Use Case is a document which contains prose. You might derive your use cases from a diagram as you brainstorm them to meet your requirements, however.

So, the bottom line. The documents for audience 1 are "what" to build. I don't think you can do a project without these documents. These are also the least likely to change.

1. Technical

These are the artifacts that are for techies, the architects, the developers, the dba’s, etc. You mentioned a lot of them, Data Models, Class Diagrams, Flow Charts, CRC Cards, etc, ad-nauseam.

Many more “formal” projects like to create all this upfront. Also you have two general approaches, start with the objects or start with the data. OOP purists say start with the objects, which are driven by your business domain. But, in practice I see most people do more data centric design and start with the database. However, as someone said above, these documents are never right. As you learn things you make changes so you have to update these documents constantly if they are to have any value.

The XP (Extreeme Programming) camp does there technical specs / design more as a brainstorming task. Once a design of something is hashed out, it is just a starting point. The artifact is designed to be disposable. It is usually done on a white board, and not as a documentation task but more as a communication tool to help multiple people discuss the design using the same notation. The end result will be “close” to the design. But, as you know, while you code stuff you discover new classes or tables or whatever. Since you design was on a white board, there is no need to go update it. So, in this case the artifacts and documentation of the design are the code (and tests if you use TDD).

So, the bottom line. The documents for audience 2 are “how” to build it. You can do a project without these documents. However, the larger the project is, and the larger the team is the more necessary these documents usually become. These are very likely to change or be disposable.

1. Management / Sponsors

The third audience for software project artifacts would be high level decision makers. These would be documents like Scope Document, Market Analysis, Competative Analysis, Risk Analysis, Cost Estimates, etc.

So, the bottom line. The document for audience 2 are “why” to build it. Or they allow these people to decide if the project should be done.

Hope this helps. It was much longer than intended.

BOb

alexdresko wrote:

Throughout most of the design process I use MindManager X5

I have a customer who is trying to turn me on to that.

alexdresko wrote:

I'll dive right into Enterprise Manager.

Am I the only one on here who does scripts??