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?
7
- 2\$\begingroup\$ possible duplicate of How should I structure a design document? \$\endgroup\$Seth Battin– Seth Battin2013-06-21 06:30:40 +00:00Commented Jun 21, 2013 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\$Raceimaztion– Raceimaztion2013-06-21 06:37:56 +00:00Commented Jun 21, 2013 at 6:37
- \$\begingroup\$ So: Design Document Contents? \$\endgroup\$House– House2013-06-21 13:48:58 +00:00Commented Jun 21, 2013 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– House2013-06-21 13:54:43 +00:00Commented Jun 21, 2013 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– Tetrad2013-06-21 17:42:15 +00:00Commented Jun 21, 2013 at 17:42
| Show 2 more comments
2 Answers
\$\begingroup\$ \$\endgroup\$
2 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\$MartinTeeVarga– MartinTeeVarga2013-06-21 14:35:38 +00:00Commented Jun 21, 2013 at 14:35
- \$\begingroup\$ Hey SM4, Thanks for the detailed outline of process. It helps me as well as others. \$\endgroup\$MogambO– MogambO2013-07-08 04:26:51 +00:00Commented Jul 8, 2013 at 4:26
\$\begingroup\$ \$\endgroup\$
1 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– Tetrad2013-06-21 17:42:35 +00:00Commented Jun 21, 2013 at 17:42