I'm working on a open world strategy game for which I'm planning to make technical design documentation.

How do we decide exactly what we need to include to ensure the design document is as complete as it can be?

  • 2
    \$\begingroup\$ possible duplicate of How should I structure a design document? \$\endgroup\$ Jun 21 '13 at 6:30
  • \$\begingroup\$ I don't think it's a duplicate. The question linked is talking about the structure, while this question is asking about the contents. \$\endgroup\$ Jun 21 '13 at 6:37
  • \$\begingroup\$ So: Design Document Contents? \$\endgroup\$
    – House
    Jun 21 '13 at 13:48
  • \$\begingroup\$ I've edited the question a bit. Asking for examples of documentation isn't a very good question, it's essentially a poll and isn't fit for a Q/A site. \$\endgroup\$
    – House
    Jun 21 '13 at 13:54
  • 1
    \$\begingroup\$ @Byte56 devil's advocate: depending on who you ask there's a big difference between a GDD and TDD. \$\endgroup\$
    – Tetrad
    Jun 21 '13 at 17:42

First important aspect to consider is: Who are you writing the documentation for? Yourself, modders, map editors/campaign designers? And second, but equally most important: What is the purpose of it? What the documentation should contain in any case is:

High-level overview

Write a short abstract what is your game about. List what have you used, programming languages, libraries, versions. System requirements. Screenshots. If you write for someone who is going to extend your game in any way, describe how to install your game in a way they can use it/mod it. Describe what your API can do.

Extension tutorials/guides

If anyone is going to implement/extend anything in your game, write a typical example. Write a tutorial. How to create a map, how to write a simple extension. Make the tutorial easy enough for people to be able to try and complete in one easy sitting, but complete enough to show the capability of your system. This might be good for you as well, when you come to your game after some time. Write guides for typical tasks in your game.

Architecture, Entities, Workflows

Draft few diagrams, how are different tiers connected. List or draft a diagram of basic entities in your game, their relationships, how are they stored (DB, ... ). If you use any custom file format, document that as well. If you use XML, don't forget to attach a and explain its schema. Create pageflows and workflows of activities in your game.

TODOs and knows issues

If you know about anything that was left out, document it. Any errors that were not dealt with, write down possible workarounds.

Detailed API documentation

Generate one from comments at least, but your comments must be good. Make sure you document all public methods and classes. Pay special attention to any publically available API you have created typically used for scripting etc.

Get someone to read it

Someone who was not involved in making the game, but with sufficient technical level. If you are going to release the game with the technical document, get an editor and technical writer to proof read it.

  • \$\begingroup\$ BTW you will probably never write a complete technical document. Antoine de Saint-Exupery said: "Perfection is achieved not when there is nothing left to add, but when there is nothing left to take away" – he obviously never wrote a technical doc. \$\endgroup\$ Jun 21 '13 at 14:35
  • \$\begingroup\$ Hey SM4, Thanks for the detailed outline of process. It helps me as well as others. \$\endgroup\$
    – MogambO
    Jul 8 '13 at 4:26

The technical design document should include the details of the technology required to create your game. It shouldn't just list the technologies, you need to explain how they're used and why they were chosen for the project. You can provide use cases, or play examples, and describe the technology required to implement those examples.

Describe how the technologies will interact and why they should interact in that way. Include descriptions of the systems that will be implemented, their uses and what aspects of the game they'll take care of.

Visually, this would include a flowchart of the structure of the code. It would include annotations of the connections, and detailed descriptions of the blocks.

  • \$\begingroup\$ Additionally it should also include technical risks and your plans for mitigating them. \$\endgroup\$
    – Tetrad
    Jun 21 '13 at 17:42

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .