Register a SA Forums Account here!
JOINING THE SA FORUMS WILL REMOVE THIS BIG AD, THE ANNOYING UNDERLINED ADS, AND STUPID INTERSTITIAL ADS!!!

You can: log in, read the tech support FAQ, or request your lost password. This dumb message (and those ads) will appear on every screen until you register! Get rid of this crap by registering your own SA Forums Account and joining roughly 150,000 Goons, for the one-time price of $9.95! We charge money because it costs us money per month for bills, and since we don't believe in showing ads to our users, we try to make the money back through forum registrations.
 
  • Locked thread
semicolonsrock
Aug 26, 2009

chugga chugga chugga
I am in the process of writing a functional design specification document for an app, and while reading up on other people's methods, noticed a huge variety. I'm sure a lot of you have written these before, and I'm curious what process you have found most helpful. I'm working with a pretty small, flexible group, so I'm focusing mostly on getting ideas structured and including a lot of wireframed examples to think through ideas as I go. The big idea being making a document which will let the people who know what the users want communicate to the programmers what they will need. What does everyone else do?

Adbot
ADBOT LOVES YOU

Suspicious Dish
Sep 24, 2011

2020 is the year of linux on the desktop, bro
Fun Shoe
A good design document is one that makes the user's problems clear to the programmers, so they can solve the problems and apply solutions in the way they know how, rather than blindly following a list of requirements.

There is no need to be any more formal than that. State the problems or needs clearly, and the recommended solutions.

Plorkyeran
Mar 22, 2007

To Escape The Shackles Of The Old Forums, We Must Reject The Tribal Negativity He Endorsed
While I've read a decent number of functional design specs, I don't really know what a good one would look like due to not having seen one.

v1nce
Sep 19, 2004

Plant your brassicas in may and cover them in mulch.
I used to do project specs and costs for an agency, but I don't know how much of this applies to straight up functional design spec. Our workflow was to do consultation with the client about what they want (3 or 4 meetings, emails, etc) and then the project manager and lead developer should have a pretty good idea of what's needed from the system. We would then write up a detailed specification document including wireframes which the client could sign off on, and then the devs would get to work.

One of the biggest questions you have to ask yourself constantly throughout writing the document is "who is this document for?". As a developer you'll be tempted to get into technical detail, but really the points you need to make are about what is going to be delivered, and not how. In your head you should be explaining a black box that already exists and what it does from the outside.

To elaborate on what Suspicious Dish said, if you're not specifying the solution itself, but rather your needs, keep the desired outcomes broad enough that the architect/project manager/developer can come to their own conclusions about the best solution to create. They can then design the correct solution and the project manager/client can sign off on what is returned by the devs. This sometimes leads to huge leaps in process efficiency, but if you need to do something in a particular way for a very good reason, you also need to state those very good reasons in your specs.

If you're specifying the actual solution, try not to get technically bogged down, but make points about what is going to be delivered. If there's UI involved, pictures really are worth a thousand words when trying to explain UI. Wireframes and flowcharts are fantastic guides for anyone, but try to ensure it'll be useful to everyone who will read the document. A flowchart explaining how the system will interact with an external API is probably going to be both useless and technically wrong, while one that explains what happens when a user books a hotel room (save booking, pass booking to external holidays API, email admin) is going to be useful.

If you're going to derive cost from the specification - be it cost of money or cost of man hours - you want to try and be "spatially aware" of the size of the thing you're writing about.
For instance, I've had a project handed to me that had a section on "content authoring", which basically described how users would be able to write blog posts. As a bullet point in that section, it said that all user content would be censored for swear words, and key phrases would notify an admin, and these lists would be manageable by admins. To me, the whole "content authoring" section felt small-to-medium, but censoring felt like it need to be an entire section by itself, and was medium-to-large.
Long story short, you really want to avoid any situation where a single line of text greatly affects the costs, or greatly affects the functionality of the thing it sits within. The amount of functionality being described should be relative to the amount of text used to describe it.

When I'm trying to outline the scope of the system and all the features, I'll usually start off from my empty page by just writing bullet point names of the major sections. Then I'll write the names of features within those sections. After that I start to elaborate on the easy stuff and write one-liners about any other parts of the system that pop into my head. Once I think I have the majority of the important stuff down, I'll begin writing the actual text of the document from the top down.
If I've done it right the structure of the doc won't change too much, but it's not a bad thing if you start juggling sections around for ease of readability, and so you can lead from one related feature into another.

Finally, the more people that can proof-read it the better. When writing about something huge that doesn't exist, it's easy to miss a feature or a requirement.
People shouldn't ever have to questions about what you're describing in the document, and someone who is a programmer should never have to ask "so if [x] then does that mean [y], too?". If you're omitting something, state that it is being omitted. As a bad example; "While deleting all of [X] will delete [Y], deleting [Y] will not delete any [X].". You may also need to state your reasons for these decisions.

I've always found it much more useful to understand a clients business and their needs and build the solution to that, than for them to dictate what they think they need. This is true not only for full-scale development but for single features. To me as developer, having visibility over all of the "why are we doing it this way" is better than a completely rigid set of blueprints. Try not to hide any useful pieces of information from your developers when building the spec.

Lord Of Texas
Dec 26, 2006

Functional specs can be a humongous trap. Don't prescribe solutions, describe the user's need, and develop the criteria must be met for the users to accept a particular solution.

If you find yourself writing "the application will have a table/button/drop-down" stop yourself. Users don't need buttons and tables, they need the ability to enter and view comments (for example). Then for acceptance criteria, you might have "users should not be able to enter comments anonymously".

The point is, if you jump straight from "we've met with the business to understand their needs" to "here's your specification code monkeys, get to steppin" you pigeon-hole the people who will actually be building the solution and obscure the core needs of the user (which leads to a bevy of problems, including misunderstand the spec). Just like you need buy-in from the business to build an application, you need buy-in on the solution from developers, or you will not end up with a quality application.

In addition, unless you are perfect in designing a solution (no one is), the spec will require revision, which is just unnecessary work. Let the application itself be the true "living" document and use the acceptance criteria in combination with frequent business demos to make sure the application meets specification.


Reading:
http://www.boost.co.nz/blog/2010/09/user-stories/
http://www.boost.co.nz/blog/2010/09/acceptance-criteria/

Lord Of Texas fucked around with this message at 19:51 on Aug 23, 2014

Jaded Burnout
Jul 10, 2004


See also https://www.gov.uk/service-manual/agile/writing-user-stories.html and https://www.gov.uk/service-manual/user-centred-design/user-needs.html#frame-the-need-correctly

Adbot
ADBOT LOVES YOU

Graic Gabtar
Dec 19, 2014

squat my posts

Lord Of Texas posted:

Functional specs can be a humongous trap. Don't prescribe solutions, describe the user's need, and develop the criteria must be met for the users to accept a particular solution.

If you find yourself writing "the application will have a table/button/drop-down" stop yourself. Users don't need buttons and tables, they need the ability to enter and view comments (for example). Then for acceptance criteria, you might have "users should not be able to enter comments anonymously".
Never were truer words spoken.

I'm currently "working" on a project as a domain architect where to "save time" the steering committee endorsed a view to write a requirements/functional spec frankenstein that completely missed the mark (set field 'A" to this, use technology "B" that we only know about to do that).

My practice formally withdrew me from the project telling them we would just do an "as built" design - if they ever went live.

About two years down the track nothing has been delivered, downstream teams are screaming about the crappy requirements and complete lack of architecture.

Long story short. Functional specs might have a place on your project - once the requirements are done correctly and there is a solid design signed off.

  • Locked thread