Creating Technical Design Documentation

I suggest this might be better in the Software Engineering forum.

I'm sure there are tons of books on this subject, but for real specs you could look on TopCoder's component library. Each component has a specification written by the designer, used by the developer. Regardless of how much you like that model, there are several hundred examples of real-life specs you can look at. You can also see higher level architecture specs, and so on, if you look around.

Yea, if this could be moved to the Software Engineering forum that would be great as it does seem better to be there.

Moved to Software Engineering.

FWIW, I only ever really use functional specs.

Quote:

Original post by Ravuya Moved to Software Engineering. FWIW, I only ever really use functional specs.

Good article. If I was writing a spec I'd focus on what the software does, which I guess is very similar. I'd want a spec to include GUI as well, because that's VERY hard to get the developer to understand otherwise.

I would ideally still have a process of software architecture though before jumping into full coding mode... trying to get at least a skeleton together in UML from the spec. When a database is involved, designing that is important too.

i.e idea -> spec -> architecture/design -> code

I think "idea -> spec" is the hard part, for two reasons particularly:
1)the guy with the idea often has no background in software engineering or technical writing
2)most programmers also don't know about writing a spec, it's a higher level skill.

In combination this leads to the very common situation - a company hires a programmer to make them some software. The company is not trained how to express their ideas technically, and the programmer is trained how to make what he's asked, not how to figure out what the customer should have asked for.

This is particularly an issue with off-shore developers, in my opinion. Contrary to the stereotypes, they often are technically competent. But they are rarely taught how to design software, only how to develop from a design.

Just a quick summary of what every class does, and a simplified UML diagram.

So mostly functional.

Depends on the scope of your project and how many engineers/designers will be utilizing the techinical documentation. If you're making a game that has less than 1 minute of gameplay, this post may not be relevant - but any moderatly scaled project should consider a more structured approach.

Technical design documents with multiple users and interfacing API's should be much more detailed as it is the road map for everyone on the project and you are certainly not going to get what you want if you dont outline it exactly and nothing will be consistent. If you are working independently, then this document can be slimmer, but it is still good to be thorough and keep yourself consistent to prevent feature creep and in general a more cohesive design.

Regardless, the technical documentation i've been trained to create or have encountered include a range of the following to describe how you are going to write, and with what.

Coding Standards
-Naming, such as hungarian
-Variable prefixing
-Structure/Class format
-Commenting templates
-Other guidelines

Development Standards
-compiler
-asset production programs & plugins
-file formats
-polygon limits
-script languages
-APIs
-etc.

After these kinds of introductions you genearlly run into the module breakdowns where you describe in detail your engines, systems, tech-features, libraries, etc.

These breakdowns typically include things such as:
-brief description
-list of features
-risk levels
-time to complete features
-psuedo-code/projected algorithms
-dependencies (could use UML)
-member lists (could use UML)
-method lists (could use UML)

In my opinion the key to a good tech doc is identifying dependencies and risks. The larger the project the more critical and ideally you should diagram both so you can identify where risks depend on other risks so you can plan on how to adress compounding risks and back-up plans.

In regards to your question and more focused the application of game design, typically your functionality document comes first (brain storm type document) and what I feel you are skipping is your design document. A functionality document will outline all the features you want, but wont typically define how they will be presented in the game. A design document is where you would outline things like interface layout, level design, character design, objects, power-ups, and other gameplay mechanics. This document would get into backstories to provide consistency and depth to your design, equations, statistic tables, state-machines, input tables, etc. for gameplay programmers to work off of. Art requirements typically in tables for things like how many polys a level or model can have, animation sets, sounds, available actions, etc.

A design document is a good step before creating the tech doc because it will further flesh out your design and what is required out of your systems. Design documents have things like an interaction matrix of game objects which will help you define dependencies between your game objects that you might not have anticipated otherwise.

Typically at the end too, you prioritize each of your documents features into different levels and put all of the identified assets and modules into work lists but that is getting more into project planning.

What JDX said is particularly relevent about knowing how to create from a design but not knowing how to create a design. I work a lot with outsourced engineering, and you dont know how difficult it is to get what you want, how you want it, with the quality you need until you have to manage a team of oursourced engineers half-way across the world producing hundreds of hours of work a day with little re-work.

You have to understand that most people work from past experience which is more often than not your experience - the better you are at documenting your requirements and design the more success you will have in the end. Being particularily detailed in your design and technical documents is invaluable time spent if you have any intentions on having someone else work on your design.

For my personal projects, I start off with a concept document. I have two templates, one for "problem solving" projects and one for "feature-based" projects, though they aren't meant to be rigid "fill in the blank" things (no such thing is possible anyway).

"Problem solving" projects are ones where there is a clearly defined need from a person or group of people. You know something is wrong or could be better, and you want to make something that will make it better. These projects are incredibly easy from an analysis standpoint, because nobody can argue with "problem solved".

"Feature-based" projects are ones that don't address any sort of need. They are tasty treats, with sugar sparkle dust and frosting. As such, they are fundamentally in the realm of taste, and therefore incredibly difficult to nail down. As with any type of cooking, the key is to know when to quit.

Since we're talking about games, that's a "feature-based" project. Here's what goes into my concept document:

Quote:

Abstract In a single paragraph, describe the idea to be developed. Conceptualization Go into detail on the various concepts and motivations of the project. What will the user be doing? What are the different ways the user can do those things? How much interaction will the user have with the project? Is there a narrative, and what is it? What is the user's motivation for interacting? Try to answer the 5 W's in as many ways as possible. Features Describe the specific features that the project will have. 2D or 3D graphics? Joystick/Gamepad or Keyboard+Mouse input? Online play or single-player only? Real-time interaction or turn-based? Constraints Describe any issues that must be taken into account that will limit the design of the solution. Are we designing for wide market appeal (thereby necessitating lower system requirements)? Exploitable Resources Describe any pre-existing resources that may be useful for the project, either in-house or 3rd party. Risks Describe the known risks facing the project. Developer's Notes Describe any technical issues that must be taken into consideration at a very early stage. For example, if the problem is known to require a non-standard security implementation, then provide notes on or links to security implementations that would be acceptable.

Ideally, this is no longer than 3 pages. Each of these sections are only a paragraph or two. It's supposed to be a quick, easy document to bang out. The quicker and easier documentation is to write, the more likely it is to be written. This document establishes the kernel of the vision for the project. It's useful for the solitaire-programmer as well as teams; the former uses it to archive project ideas to access at a later date, the latter uses it to get everyone on the same page. If I feel like writing more than 2 or 3 pages, then I continue to write more, but I try to get at least this information down.

From here, the templates break down. You can't really templatize a large project document. There are some common themes, and it's nice to have a standard styling to all of your docs, but ultimately you have to do what is right for your project. I think templates too often tend to restrain people in that regard. So instead, I try to answer the "5 Ws+H": Who, Where, When, Why, What, and How".

Who: your team. Probably just you. This is important because it informs every other decision you make. You can't build a project around people who are lacking key knowledge. Does your "team" know enough about databases to succeed? If not, make it so (find someone or learn).

Where: this is more of a feature question than a literal geographical sense. Where is this project going to run? Is it full-client, is it web-based, is it a hybrid, is it mobile? Figure out the answer, and revisit your team's capabilities. Or, maybe you come to an answer based on the capabilities of your team.

When: RIGHT THIS FREAKING SECOND!!! No, not at all. Recognize that projects take time, lots of time, and you will have delays along the way. Try to set a goal for when you want to see the project finished. Say 6 months from now, or a year, or whatever. This is going to influence your spec in a lot of ways. For example, no point in including MMO features in a 4 month project. But your spec is also going to influence your timeline: we really want to include motion tracking features, so we have to extend the deadline.

Why: I've found that a lot of people fail to answer why they want to build a specific project. It's going to be your motivator, so it has to be good. It's completely up to you though, I can't answer this for you.

What: Here, we figure out exactly everything that's going in to the project. HA! No, we get an idea of everything that we want, and then we revisit our past assumptions and continue forward. I start molding a functional specification from my initial concept document. What features do we want? How is the user going to interact with it? Write down lots and lots of notes. Move through each section in the concept, and figure out everything you're going to need to cover those things. Organize those notes into sections that deal with similar problems: logic, security, interface, file formats, story, art resources, etc. This is an excellent opportunity to do a lot of research. Don't know what goes into making a networked game? Start researching them, read as much as you can on the subject and try to find solutions that feel good (because you're not likely to stick to your own solutions unless you actually like them). When you are done, you should have a very good understanding of exactly WHAT you are making.

How: After the functional spec, you can go on to a technical spec. To me, this isn't critical to do as completely as the functional spec. It's an excellent opportunity to learn how to use new libraries and project architectures. You have to figure out exactly how all the pieces go together. I tend to think that a lot fo this is done hand-in-hand with coding the project. It's good to have a lot of thumbnail projects that you can use to do all of your dirty learning before putting it into the real project. Trying to get as much of this down on paper before you start "real coding" is also helpful to make sure everything is self consistent.

If you haven't noticed yet, there is an overarching theme of continuous refinement of every step. You're never done with one step when you move on to the next. I do a lot of "programming" during the design phase, and it's all throw-away code, never makes it into the production model. It's all for figuring out how things work, and how they go together. I do a bunch of "designing" during the coding phase, because I run into situations where new information throws up obstacles that need to be handled.

The fundamental thing to realize is that this is the longest part of the project. In my daily career work, I write a lot of documentation for projects that I will be coding for my clients. Ultimately, I probably spend 10% of my time on actual programming. This is an important distinction, because it means that the code is really not that important. Yes, it's where the rubber meets the road, but it's such a small part of the project, and so informed by all the other processes in the project, that one should not feel any sort of affinity to it. It's there for a purpose, and if it's not serving its purpose, then it needs to be discarded and replaced. Too often, I see people clinging to code bases that they insist must stay because "we spent so much time writing it". In economics, that's called "sunk cost", and chasing it is folly.

I would recommend that you read about 4+1 view to get an idea how you document your project:
http://en.wikipedia.org/wiki/4%2B1

Then at RS Pressman and Associates you can find templates for Software Requirements Specifications (SRS), Software Design Specification (SDS), test plan documents and possible any other document that could be useful for your project.
http://www.rspa.com/spi/documents.html

To make it simple, you probable want an SRS that states what you (or your customer) want the software to be able to do. This is often done with use cases.

Then you have an SDS that gives a technical documentation how every use case in the SRS will be implemented, this often include UML Class, Communication and Sequence diagram. It is very important that everything in the SDS can be traced back to a use case in the SRS, if you have use cases which are not mentioned in the SDS or classes/function in the SDS with no use case there is something wrong...

Know that you can document exactly everything in the deepest detail, what is important is that you learn what type of documents your project needs and how much in detail you will document. This is quite hard and the way to estimate this is experience.