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?
|show 2 more comments|
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:
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.
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.
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.