Design Advice on how to write a great Technical Design Document?

Hi All,

You may have seen me recently posting on the Job Board looking for social programmers. As you might be able to surmise from the job description, it's going to involve a lot of good communication. I've been building the one project for several years now, and the code has gone completely off the grid in regards to GM's built-in scaffolding. To give you an idea, there's one object and one room, I've turned off the application surface, and I'm manually handling my view matrices. "Instances" are arrays, and classes are "objects". Objects are just heavier arrays. There's not too much value left in the GM Docs, and I'm realising I'm going to need a reliable source of information to resort to, if I'm going to have any success working with a second developer.

Now, I've written Game Design Documents before, and am well versed in the art of concept-laden verbosity. The project I am hiring for has several GDDs, one each for the various games that are being developed within it.

So, my question to you smart people: How do I write a Technical Design Document that is not overwhelming to beginner programmers, informative enough to keep them coming back, and Big Picture enough to keep us on track of our broad-stroke goals? Does anyone have any experiences with hiring fresh developers onto big projects that they'd like to share? I'm genuinely worried that all I can offer an onlooker is a brain-frying information dump.

Thanks in advance!
 

curato

Member
Just from your first paragraph, It doesn't sound like that is green programmer territory there. The real trick to working with a bunch of people is breaking the work up into small pieces that can be worked on separately. There are going to be some things that more advanced than others and you as the project manager need to decide who can do what and assign the work to the correct person.
 

Yal

šŸ§ *penguin noises*
GMC Elder
The original Deus Ex project's GDD supposedly started with a list of ten "commandments" that everyone must always adhere to; it concerned level/mission design rather than coding style, but having the core tenets of your code design be summarized up-front as terse, mandatory axioms would mean that people already know 90% of what you want them to know after they've read the first page. Then you can spend the rest of the document on nitty-gritty details that might be important to look up if needed, but not important enough to memorize upfront.

Other than that, i personally prefer having code that documents itself.... i.e. write comments that explains the purpose of a chunk of code, not how it achieves this thing it does - that won't help you if you don't know what it's trying to do, and you can always just look at the code to tell what it's going. Whenever someone wants to know how a certain piece of code works, they can read the comments in that file.

Another thing I'm fond of is enforcing special //TODO labels for unfinished code, //HACK labels if something depends on a special assumption and will break if the assumption is broken later, and //NOTE labels to point out important gotchas (e.g. non-standard input ranges like one-indexed counters). You can easily find unfinished business by finding all //TODO labels, and if something breaks for seemingly no reason, you can quickly check if there's any //HACKs you might've violated.
 
There are going to be some things that more advanced than others and you as the project manager need to decide who can do what and assign the work to the correct person.
Yeah, that's a good point. I'm in the throes of hiring some help right now - do you think I would benefit from contracting out to an experienced project manager first in order to best gauge the difficulty of work? My usual process for work delegation is to press F5 until it does what I need it to do. I definitely need to step my game up in that department.

The original Deus Ex project's GDD supposedly started with a list of ten "commandments" that everyone must always adhere to;
That's cool. I can definitely see how some broad-stroke influences in code style could benefit in the long run. I also like the idea of developing a backbone set of ethics/code-philosophy, so that both the employees and the employer are on the same page of what's expected of them. As for the comment suggestions, I totally agree - and am definitely all over that. Sometimes writing comments for invisible helpers at 3am is all you need to keep the enthusiasm train running. I do prefer the "!todo" style though, so I can search for "!___" commands with impunity.

As a follow-up question, do either of you have any good ideas of practices I could employ to help keep my code-base protected? I understand that trust is a large component in business, but I would like to find ways to mitigate my exposure to risks of IP theft. There is a lot of custom code in this project that took several years to develop :/
 

curato

Member
there isn't a whole lot you can do to prevent that once you allow other developer in to your environment. The only thing you can do it is have people work on standalone functions or OOP classes that would work independently of your game and you could do the integration. Once people are plugging things into the project as a whole and testing them they basically need access to the entire thing to test it. If you want to break it out seperate you have to give them specifics on the input required and the required results and maybe even some test data to run it against to verify that it will work with what you are doing.
 
Top