#begin
Lets discuss the first section called “The Requirements Pit”. If you have attended some formal computer science education, or maybe more specialized in regard to gamedev you might know that courses describe requirements engineering or elicitation as a early project stage. David and Andrew say that the word ‘gathering’ in requirements gathering implies some sort of happy analysis of requirements that are already there. You merely have to find them.
However, if you have been in the industry for longer than a few days you know it doesn’t quite work that way. Even when you have a detailed description of what needs to be done, there’s room for interpretation and even things that might get lost in translation. Both from just one language to another if you are working on a bilingual team, and translations lost from thought to writing. Sometimes it can be really difficult to write your thoughts down. I bet you’ve experienced that before.
David and Andrew say that: ‘Requirements rarely lie on the surface. Normally, they’re buried deep beneath layers of assumptions, misconceptions, and politics.’ Thus you don’t gather requirements, you dig for them.
So how exactly do you dig for requirements? They start with a good formulation. A requirement should be a statement of something that needs to be accomplished. I remember a course in UNI that was specifically about requirements engineering. It was called goal oriented requirements engineering. It was based on a book called Requirements Engineering: From System Goals to UML Models to Software Specifications. It’s the most comprehensive book about requirements engineering I’ve read so far, and probably ever will be because the topic is not really spectacular. It’s kind of boring and dry, yet very important.
David and Andrew mention that it’s very important to discover the underlying reason of certain requirements. I’ll give you a simple example: The player can only attack this npc with a weapon that can pierce armor.
A simple way to implement this requirement is just adding two booleans, one on the npc for wearing armor or not, and one on the weapon wether it can pierce armor. But, I think you already guessed what we need right here; we need some kind of system for defining weapon damage and armor values. Why? Well because these kind of policies change. They are highly volatile, and often might be bound by level difficulties and such. So, the underlying requirement would be that we need to specify how weapons and armor interact.
In the end of the day, your development must solve a business problem, not an implementation problem by simply meeting the stated requirements. This means you must document the reasons behind requirements since it is invaluable information for you and your team to make decisions. I and fully agree with them.
Next David and Andrew describe a technique for getting inside your user’s requirements they think is not used merely enough and it is; become a user yourself. Haha. I think this problem exists far more in the business software space than it does in gaming. I think all of us are users of our own games. So eating our own dog food is something we do on a daily basis. And I think that’s a great benefit we have as gamedevs. Our passion for the thing we are building is often very large. This gives is a drive to keep on improving and testing to make something just absolutely perfect. But it can also be a dangerous weakness since this passion can easily be exploited by greedy corporations. They might exploit your passion to work massive overtime during crunch periods and then dare to do layoffs. So be very careful of it. Well sorry for the rant, I had to bring this up since it’s a hot topic lately with all the layoffs going on.
Documenting Requirements
But how exactly would we document requirements. It’s not just throwing a few lines down on paper describing something in a vaguely manner. Its best to have some measurable or quantifiable goal to write down.
David and Andrew mention that most of the functional requirements can be written down as the system’s use cases. They also mention Ivar Jacobson’s book: Object Oriented Software Engineering, A Use Case Driven Approach. It’s a great book you can find some reviews right on this blog by searching for it.
But I think you might have heard of use cases before right? It are common scenarios your system or game needs to be able to execute. A simple example might be: “The user can navigate to a store and buy items for a certain currency that end up in their backpack.” The use case can then be extended with some pre and post conditions like “the user needs x amount of currency to buy a product” and “after purchase the item will appear in the bag taking up either a new slot, or be stacked if it’s a stackable item”. We should also describe some error conditions like when the user doesn’t have sufficient funds and describe usecase variants. Maybe there are special kinds of vendors, or simply the execution path of filling a new slot vs. stacking items might be a variety. Although that better fits use cases related to bag management or something.
David and Andrew do mention something interesting and that is that Ivar didn’t elaborate on the exact details that should be in the use case description. Should it be formal or informal and what data can be in there. That’s why there are an infinite number of use case documentation templates. In one of his talks, Uncle Bob says, that every software consultant in the 90’s needed to have his own use case template and that’s how they grew into these monstrosities which would take an hour to fill in. Uncle Bob also often talks about the fact that the use case descriptions are meant to be somewhat vague since we do not want to bind ourselves to implementation details or technology yet. If your use case for “Retrieving items from the store” mentions there is a database connection to an sqlite database, you have already lost the architecture game. These kinds of decisions can be made later in the process. We can use abstraction and inversion of control to hide the details of the database and simply implement the use case. That’s clean software design, remember?
David and Andrew mention that one way of looking at use cases is to emphasize their goal-driven nature. This aligns perfectly with what I described before. If you want to know more about goal oriented requirements engineering, make sure to check the book out.
Next they show an example of a use-case:
The example they make is a use case called ‘Buy Goods’. It’s basically a use case for placing an order. The template they use is rather extensive but the good part is the fact that the formulation remains on the domain level and doesn’t describe any technology or implementation details. They also promote the idea to use a template for describing these use cases since they will remind you of edge cases and relations to other use cases.
Use Case Diagrams
Andrew and David also bring up the idea to encode use cases in diagrams. The UML specification provides such concepts so we might as well use them. I’ve always likes use cases diagrams because they are very simple, easy to understand and will most likely give a good representation of what the system does. These diagrams can also show the relationships between the use cases such as ‘using’ or ‘inherits’ relations. Funny thing though, David and Andrew say they think it seems incredible that anyone would document use cases with stick figures and some lines. Haha, yeah they are correct, these diagrams are complimentary to the descriptions in the tables. They also mention you should not be a slave to a certain notation, which I think is a really great piece of advice.
Overspecifying
And next they mention the problem of being too specific with requirements specification. Good requirements remain a bit abstract. They allow for some wiggle room. Details should be filled in later like what database or software architecture to use. David and Andrew also want to remind you that abstract doesn’t mean vague. Requirements must be very clear about the business context and reflect it in the best way possible. You must capture the policies, invariants and semantics of each requirement. Yet that doesn’t mean you need to add information about what design pattern you will use or the physical location of a database. These details are very important, but not yet. We will more about this in just a bit.
Requirements elicitation will give you a lot of understanding of the business domain. This understanding will help you a great deal when implementing systems, especially if you’re using domain driven design approaches. This understanding will also help you understand how the system might evolve. Remember the example I gave about the armor piercing weapon. Understanding the domain of let’s say RPG’s will definitely bring more context to how such a requirement might be implemented. Most RPG’s have some kind of gearing and weapon system which takes are these kinds of requirements. This way you might be able to ‘predict’ what requirements might come next. And I say predict in the slightest intention of the word because its bad practice trying to predict what your users want, since you will often be wrong. But your domain understanding of RPG’s will help you anticipate requirements and fit them inside the gearing system, or the level system, talent trees, shop system, housing system, you name it.
Just One More Wafer-Then Mint…
David and Andrew then mention the idea of scoop creep. I bet we’ve all experienced that before. Some feature is described and can be implemented fairly quickly, but then you find some other stuff that might benefit from this change and a whole chain reaction is kicked off. This happens to me sometimes as well. A quick simple refactoring enables me to understand more about the system I’m writing and suddenly this door opens and I can restructure the entire application to create a more cohesive design. This happens to me especially when the code I wrote is tracer code. Remember tracer bullets from previous blogs? It’s production grade exploratory code.
But Andrew and David put some emphasize on keeping your guard up in regard to scoop creep or requirements creep. They say that the key to managing growth of requirements is to: “point out each new feature’s impact on the schedule to the project sponsors.” This way you can point out, accurately, of how and when requirements growth occurred. It will keep the grips on the dreaded notion of “just one more feature”.
Maintain a Glossary
Next they mention the concept of a project glossary. This is a document that lists all the domain concepts. I think this is really great. Its basically what DDD is all about. I wonder if Eric Evans took some inspiration from The Pragmatic Programmer when coming up with the ideas in DDD. So when we compare the project glossary to DDD its a document that describes the so called ubiquitous language and it’s main purpose is to accurately define the terminology for a given context. And remember, terminology can change depending on the context so you might have different glossaries per component. I’ll give you a simple example: Let’s say we are building a single player adventure game. In our game we have the concept of a player, which maps to the character the user is controlling. But we also want to show cut scenes and within the bounded context of some cut scene component “player” maps to the video player that will render the video. These things can be documented in such glossary.
Get the Word Out
And the last topic David and Andrew want to touch on is the fact that once you have gathered all the requirements; please make sure you get the word out. Distribute the documents to as many stakeholders as you can. In the book they mention the fact that some form of hypertext is most desirable. Haha, I mean, it’s 1999 when they wrote it. But they are right, hypertext, when you can click on links within the document is really helpful navigating such documents. Imagine if you would need to find stuff on wikipedia without clicking on links to related topics. That would suck big time.
#end
01010010 01110101 01100010 01100101 01101110
Recent Comments