What qualities made it so great, and what made it stand out compared to the not-so-great specs that you've had to deal with? Or, if you've never worked with a good functional spec before, what sort of things would you expect in a great spec?
Sorry this is obviously subjective but I'm creating a functional spec (not my first) and it just occurred to me that I may get some good ideas from the bright folks on SO!
The Project Aardvark specs from Joel on Software are the best I've come across so far. Each screen is defined very well, with pictures. The main features of the software are described, as well as some technical details.
Sadly the specs I've received personally aren't that brilliant. Usually they are just a bulleted list of features they expect from each section of the system, and they expect you to work out all the details. Which is fine, I guess. However, I'm writing a game design document for an RPG game I'm working on as a personal project, and I think the specs I'm writing are very well written. I've divided the game into Sections such as
Characters
Weapons & Armor
Levels
Map
Physics
and so on, and described each section in terms of gameplay as well as some technical details. Its very easy to work through.
I also highly recommend reading the Painless Functional Specs Series from Joel on Software for anyone interested in writing better specs.
IMHO, a key quality should be that the functional spec specifies the "what" in great detail but not the "how". That way, the requestor (marketing?) gets the look & feel and feature set that they want, but the implementation is left to those who know it best -- the developers.
Obviously, the specification should be complete, consistent and comprehensible. IMO it should also be well-organized, in that it keeps all requirements for a specific part of the product together. I've more than once read specifications where requirements for some module were scattered throughout the whole document, e.g. the general description is in chapter 4, but additional requirements can found in clauses in chapters 2, 5, 7 and appendix B. To work with such a specification, I first have to create a cross-reference map of requirements to modules.
A good spec should state what the application is supposed to do, in a clear manner.
This seems obvious, but the stuff I usually get is often very vague. Apparently it's not very easy for people to express what they want on paper, IF they even know what they want.
Related
I'm writing an iPhone game and I am trying to write some requirements documents. I have never written requirements before so I got the book Software Requirements. I have not finished it yet, but I forsee some issues, as this book is targeted towards a business. My main question is I am the only person involved with this game and I feel the main purpose of the requirements document should be to nail out as many conceptual ideas of how the game works as I can before I am deep into design or construction. Does anyone have suggestions on how I should lay this out, should I still try to mimic the template provided in the book where it makes sense, or since I am both the sole developer and product owner, should I just stick to game concepts?
You're right that traditional SRS documents don't really fit games documentation all that well. Games instead have a general Game Design Document. It's usually created before any work on the game begins, and it's often edited as the development process goes to keep straight the intended end-result and specifics of the game.
While business software requirements documents are like contracts between a client and developer on what to produce, game design docs are more often specifications from the designer to the artists and programmers on what exactly they need to develop.
There is no specific layout to use. But you should consider who you're writing the document for. Is it for a class, for yourself, for peers after the project is done? The level of detail and the kind of things you include will be different depending on your audience. The format itself is very flexible, as long as it's coherent.
Brenda Brathwaite has a good blog entry on this subject which you might find helpful.
There is a semi-recent article from gamedev.net on the subject as well.
[Poor Jacob, you just read a book on the topic, and, collectively, the SO community writes another one for you, along with extra links, and probably with diverging views ;-) ]
Although I'm not familiar with the book you mention in the question, I think that the following suggestion may help you both take seriously, but also relax a bit, about the all too important question of requirements.
Being a "team of one", it is particularly important, and somewhat paradoxical, that you go through the effort of formalizing the requirements. However, rather than putting too much emphasis on the form, you may find an Agile approach to developement (and hence to requirements gathering) more appropriate. With regards to requirements, one of the main advantages of this approach, is flexibility, i.e. the understanding that while they should be formalized (with limited time/effort), requirements should be allowed to change (within limits) as part of an iterative process towards production of the target product.
In very broad terms, this generally go as follows:
write "user stories", these are individual "cards" (yes, physical cards, say 4 inches by 5 inches, are good, for you can then move then around, sort them etc.)
each story tells a particular feature of the application, here the game, from the end-user's perspective. You can/should start all cards with "As a user, I need the game to..." then follow with a particular feature, for example "... show my high score on the same page as the global high-scores are kept [because ... here optional reasons for why user may want this feature].
review each story and assign a rough estimation of the time involved in implementing it
review each story and assign a priority level (scale may vary, but something simple like "Must have from Version 1.0", "Should eventually be in there, for sure", "Would be nice to have" and "Maybe nice to have...")
organize releases, on the basis of what you can do within say 2 or 3 weeks, maximum. If a particular feature were to take too long, schedule it for a later release.
implement the features assigned to the current release
iterate through this release cycle, reviewing the requirements as you go, for the relative importance of features, and also the need of new features may become evident as with the insight provided by using the [incomplete/imperfect] intermediate releases.
Books like the one you describe are focused at a different audience, but there is value in the general concepts presented. Fully developed requirements documents are not as common as you might think. Don't let anyone think that you are a 'bad developer' for not having the most detailed requirements.
Requirements docs might be more important if you need to communicate the requirements with a co-developer.
If you are the sole developer I would strongly recommend that you spend your efforts on the design and implementation of the game, over requirements. If you have a good idea of what you build then let this flow as you build it.
Documentation can help you. The question is what is going to be most beneficial. Maybe design decisions are more critical than requirements for you but not for others. You'll maybe want to have a list of things that people have requested or ideas that you think of but cannot implement straight away. Sometimes a whiteboard can be handy for sketching out things, it's not just a tool for collaboration with other people.
Here's just a general approach...
Solidify the concept...write it in plain English first (ex: The game is a first person shooter. You kill zombies and hunt for treasure.)
Get a paper pad and pencil and draw out the general flow of the game and the main screens the users will encounter...main menu, options screen, help, etc. Make sure it makes sense.
Go to a site like mockingbird and create the detail wireframes for your screens...
Print these out and do some paper prototyping...i.e. put the printout in front of you and 'click' on a button...then bring up the appropriate screen...then click on another button, etc.
Once that makes sense, you can try to start coding your game.
Personally I believe you should use your own way to do this. The most commonly available one's will not match with your requirement. They might be suitable for a common commercial server application but not for a game. And since iPhone gaming is a new trend you may have to look in a different perspective.. You may not be able to fill a document with standard requirements and you may have different set of New type of requirements.
Just a suggestion... Sign up with Google Sites, and create a private site with documentation of the game, requirements, technical aspects, work log, etc... You can share it with select people, and it always keeps edit history.
I like it better than a Wiki because it is more structured, and just plain simple to use.
I've been asked to run a workshop and coding dojo soon for people to try out Scala and try to build something with it. The attendees are all going to be new to Scala, and could come from any of a number of languages (I'm presuming they can code in at least one mainstream language - I'm including syntax comparisons with Java, C#, Python and Ruby).
Part of the appeal of Scala is that it's practical - you can use it as a drop-in "power Java" (Java with less syntactical clutter, closures, immutability, FP, traits, singleton objects, nifty XML handling, type inference etc.) that still runs on the JVM (and on the .NET CLR supposedly) and doesn't require you to change build tools, server infrastructure, libraries, IDEs and so on. Most of the katas I've seen have been fun but not 'real world' - mathematical challenges like Project Euler and so on. These don't seem appropriate as we're trying to explore the use of it as a practical, real world language that people could consider using for both hacking and work, and because people aren't necessarily going to be too familiar with either the deeper parts of the Scala syntax or necessarily of the concepts behind functional programming.
So, has anyone come across any more practical, everyday katas rather than arithmetical 'problem solving' ones? Katas, that is, that can test whether the language, libraries and tools can satisfy the use cases of the actual day-to-day programming most people have to do rather than testing out. (Not that the impractical ones aren't fun, but just not appropriate for the kind of thing I've been asked to run.)
If I can't find good examples, I'm thinking that it might be useful to try and build something like a library catalogue - the event is for programmers who primarily work on building infrastructure for universities (and in education and culture - museums, galleries, schools, libraries and so on). It's a bit boring though, but it's the sort of thing that the attendees work on in their day-to-day existence. Any suggestions?
There is a creative commons licensed introductory training course with hands-on exercises here:
http://github.com/javaBin/scala-training-slides
http://github.com/javaBin/scala-training-code
The slides are in Open Office format. If you don't have this installed, you can upload them to SlideShare, which will convert them for online viewing.
Most of the programming examples in my blog are, effectively, coding dojo exercises. Particularly the matrices series, but also the puzzles and 99 beers. Now, don't disregard the matrices series as being "mathematical", because the problems I concern myself in it are related to the construction of classes in Scala, not to doing fancy algorithms. In fact, I pretty much skip over the mathematical algorithms themselves.
Now, 99 Scala Problems and pretty much everything from Project Euler are nice exercises for the functional part of Scala, but I understand that not to be your emphasis. I do recommend retronym's answer. Rosetta Code, not being functionally oriented, might have more general examples. There are many with Scala examples, of course, though you may wish to consider other tasks as well, for ideas.
There's lot of cool things to learn about Scala, but one has to be careful at beginner level. For instance, I would not speak of dependency injection (self types and the cake pattern) or of type classes (the pattern that simulates such with implicits).
Do look as well at the material on the Scala Lang site, particularly the Scala by Example document.
EDIT
I have now overseen several Scala dojos, so here's a bit of stuff I've learned from then:
Problems: they have to be fun, not-quite-easy, not-that-hard, and that has to be everyone's opinion.
We use the Dojo Puzzles site, which is in Portuguese so it won't be of use for most people here. If there's a similar site in English, I'd love to hear about it.
The way it works is you ask for a random problem, look it over and discuss to see if you'll pick it up or not, and then indicate by saying you'll use it, you'll not use it, or maybe you'll use it but you'd like to see another one. This vote gets registered and you can see how many people picked up a problem, which helps deciding whether to pick it up or not in first place.
Scala knowledge: it turns out it's not that important to introduce key concepts of Scala language beforehand, particularly if some of the participants have basic knowledge.
In my experience, setting up the testing environment with a trivial "pass" test and explaining how people should write the tests is often enough to get people started. If you feel someone is struggling to write something, give a quick explanation and get on with it.
Teaching Scala: if you do set out to teach Scala, keep lessons short and follow up with a dojo. In this case, keep a set of dojo problems that are adequate to the lesson, and, depending on how many lessons you want in one day, short.
It helps imposing artificial constraints on how one must solve a problem. Some examples of constraints I have put in practice are no classes and single-expression methods (that is, no multiple statements or val/var declarations). The point of these constraints is making it impossible for people to solve the problem in the way they are used to, which gets them to explore the language in search of alternatives.
I have the final results of three dojos done at my current job in this repository.
At the moment we are using the Randori Kata format, but without fixed time or break, and with retrospective at the end of the dojo, not at the beginning of the next. This, however, is just were we are currently at -- we have experimented many variations, and we are still evolving.
Perhaps you could have a look at the Ruby Quiz material for inspiration.
Take a look at Scala by example from Martin Odersky (creator of scala)
I have noticed that when writing specs you waste a lot of time on things, that later, when you write your app are negligible, and you forget some important stuff.
I have found it to be faster (for me) to write a proof-of-concept application (no good error handlers and security stuff, minor gliches in the style etc) and use that as a spec for those who join me.
Still, I feel I am wasting time in this method too, any good ideas on how this should be done?
Seems like you're arguing in favor of Agile Development
Using this iterative process, our team is able to "rank" features on a scale of importance and then weigh the release date with the features they want (in a nutshell)
Joel On Software has an article about this you may find helpful. I think this question and the answer is quite user-specific and subjective though.
An interesting approach to a spec are "tests". For high-level stuff you write acceptance test using tools like Fitnesse and for low-level stuff you write unit-test.
Once a dev is done with coding, running the test suite verifies that all the spec is really working.
This approach expects that the person who writes the spec is capable of expressing himself in terms of tests. This is usually not true and therefore this approach is more like an utopia. But still, you might try it.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 10 months ago.
Improve this question
I've never written functional specs, I prefer to jump into the code and design things as I go. So far its worked fine, but for a recent personal project I'm writing out some specs which describe all the features of the product, and how it should 'work' without going into details of how it will be implemented, and I'm finding it very valuable.
What are your thoughts, do you write specs or do you just start coding and plan as you go, and which practice is better?
If you're driving from your home to the nearest grocery store, you probably don't need a map. But...
If you're driving to a place you've never been before in another state, you probably do.
If you're driving around at random for the fun of driving, you probably don't need a map. But...
If you're trying to get somewhere in the most effective fashion (minimize distance, minimize time, make three specific stops along the way, etc.) you probably do.
If you're driving by yourself and can take as long as you like, stopping any time you see something interesting or to reconsider your destination or route, you may not need a map. But...
If you're driving as part of a convoy, and all need to make food and overnight lodging stops together, and need to arrive together, you probably do.
If you think I'm not talking about programming, you probably don't need a functional spec, story cards, narrative, CRCs, etc. But...
If you think I am, you might want to consider at least one of the above.
;-)
For someone who "jumps into the code" and "design[s] as they go", I would say writing anything including a functional spec is better than your current methods. A great deal of time and effort can be saved if you take the time to think it through and design it before you even start.
Requirements help define what you need to make.
Design helps define what you are planning on making.
User Documentation defines what you did make.
You'll find that most places will have some variation of these three documents. The functional spec can be lumped into the design document.
I'd recommend reading Rapid Development if you're not convinced. You truely can get work done faster if you take more time to plan and design.
Jumping "straight to code" for large software projects would almost surely lead to failure (as immediatley starting posing bricks to build a bridge would).
The guys at 37 Signals would say that is better to write a short document on paper than writing a complex spec. I'd say that this could be true for mocking up quickly new websites (where the design and the idea could lead better than a rigid schema), but not always acceptable in other real life situations.
Just think of the (legal, even) importance a spec document signed by your customer can have.
The morale probably is: be flexible, and plan with functional or technical specs as much as you need, according to your project's scenario.
For one-off hacks and small utilities, don't bother.
But if you're writing a serious, large application, and have demanding customers and has to run for a long time, it's a MUST. Read Joel's great articles on the subject - they're a good start.
I do it both ways, but I've learned something from Test Driven Development...
If you go into coding with a roadmap you will get to the end of the trip a helluva lot faster than you will if you just start walking down the road without having any idea of how it is going to fork in the middle.
You don't have to write down every detail of what every function is going to do, but define you basics so that way you know what you should get done to make everything work well together.
All that being said, I needed to write a series of exception handlers yesterday and I just dove right in without trying to architect it out at all. Maybe I should reread my own advice ;)
What a lot of people don't want to admit or realize is that software development is an engineering discipline. A lot can be learned as to how they approach things. Mapping out what your going to do in an application isn't necessarily vital on small projects as it is normally easier to quickly go back and fix your mistakes. You don't see how much time is wasted compared to writing down what the system is going to do first.
In reality in large projects its almost necessary to have road map of how the system works and what it does. Call it a Functional Spec if you will, but normally you have to have something that can show you why step b follows step a. We all think we can think it up on the fly (I am definitely guilty of this too), but in reality it causes us problems. Think back and ask yourself how many times you encountered something and said to yourself "Man I wish I would have thought of that earlier?" Or someone else see's what you've done, and showed you that you could have take 3 steps to accomplish a task where you took 10.
Putting it down on paper really forces you to think about what your going to do. Once it's on paper it's not a nebulous thought anymore and then you can look at it and evaluate if what you were thinking really makes sense. Changing a one page document is easier than changing 5000 lines of code.
If you are working in an XP (or similar) environment, you'll use stories to guide development along with lots of unit and hallway useability testing (I've drunk the Kool-Aid, I guess).
However, there is one area where a spec is absolutely required: when coordinating with an external team. I had a project with a large insurance company where we needed to have an agreement on certain program behaviors, some aspects of database design and a number of file layouts. Without the spec, I was wide open to a creative interpretation of what we had promised. These were good people - I trusted them and liked working with them. But still, without that spec it would have been a death march. With the spec, I could always point out where they had deviated from the agreed-to layout or where they were asking for additional custom work ($$!). If working with a semi-antagonistic relationship, the spec can save you from even worse: a lawsuit.
Oh yes, and I agree with Kieveli: "jumping right to code" is almost never a good idea.
I would say it totally "depends" on the type of problem. I tend to ask myself am I writing it for the sake of it or for the layers above you. I also had debated this and my personal experience says, you should since it keeps the project on track with the expectations (rather than going off course).
I like to decompose any non trivial problems loosely on paper first, rather than jumping in to code, for a number of reasons;
The stuff i write on paper doesn't have to compile or make any sense to a computer
I can work at arbitrary levels of abstraction on paper
I can add pictures and diagrams really easily
I can think through and debug a concept very quickly
If the problem I'm dealing with is likely to involve either a significant amount of time, or a number of other people, I'll write it up as an outline functional spec. If I'm being paid by someone else to develop the software, and there is any potential for ambiguity, I will add enough extra detail to remove this ambiguity. I also like to use this documentation as a starting point for developing automated test cases, once the software has been written.
Put another way, I write enough of a functional specification to properly understand the software I am writing myself, and to resolve any possibile ambiguities for anyone else involved.
I rarely feel the need for a functional spec. OTOH I always have the user responsible for the feature a phone call away, so I can always query them for functional requirements as I go.
To me a functional spec is more of a political tool than technical. I guess once you have a spec you can always blame the spec if you later discover problems with the implementation. But who to blame is really of no interest to me, the problem will still be there even if you find a scapegoat, better then to revisit the implementation and try to do it right.
It's virtually impossible to write a good spec, because you really don't know enough of either the problem or the tools or future changes in the environment to do it right.
Thus I think it's much more important to adapt an agile approach to development and dedicate enough resources and time to revisit and refactor as you go.
It's important not to write them: There's Nothing Functional about a Functional Spec
Where I work, people don't like to write specs. (Boy, does anyone?) So they don't do it, unless forced by their bosses. If they are forced to write them, they make them as short as possible. (By the way, they also includes me.)
This results in specifications like
This software logs the time between event A and B to the event log
Name and path of parameter X are set in a configuration file in ini format.
The software is active without a user needing to log on to the computer (implementation as a Windows service)
This example is taken from a very small project, and it worked out pretty well, But I don't think that it will suffice for anything more complex. I did not specify OS/hardware requirements because this is in-house development and we have company or department standards covering those.
So my question is:
What do you consider the absolute minimum level of detail in a functional specification for any non-trivial software?
IMHO the important thing about Functional Specs (and all other formal methods/tools for software development and project planning (Yourdon, SSADM, PRINCE2, UML, etc) is that they encourage good practice by making you think along common lines.They don't guarantee success but they encourage success by formalising good practice
So the fact that FSs are created is a good thing, even if perhaps they could be better. Some planning and preparation is better than none at all - which is what a lot developers do.
What should ideally go into a FS? As much as is necessary and as little as possible. Just because some functional specs cover X, Y & Z doesn't mean yours should. If you become too prescriptive, you will add unnecessary bureaucracy to simpler projects; correspondingly, for complicated projects, a prescriptive approach might encourage the developer to stop short of the level of detail that they really ought to go to.
Joel on Software wrote a cracking article on specifications.
You can find it here
Specification Discussion