How to keep documentation when developing a game — interview with Konstantin Sakhnov

Alexander Semenov, App2Top: Kostya, hello! In this interview, I want to talk to you about documentation. The topic, it would seem, is not very complicated, but, in fact, with a huge number of pitfalls. Are you ready?

Konstantin Sakhnov

Konstantin Sakhnov, Vengeance Games: I will be glad!

Great. One of the first questions faced by the young team is: what is the documentation?

Konstantin: If we are talking specifically about team development, then one of the most convenient and popular solutions is Confluence. Among its advantages are integration with Jira, Trello and Slack.

But there are also nuances. Confluence is difficult to use while in Russia. First, you need to have a foreign card for payment. Secondly, when working with a Russian IP, emails are received notifying you of account blocking after 30 days.

This means that to work with the tool, you will need a corporate VPN for the entire team, or move from Russia.

If you are an indie loner, then Notion may well be an alternative.

Unfortunately, I have not yet been able to find Russian analogues of Confluence or Notion, which could cover all the basic needs of developers in terms of documentation. But I liked the Weeek service.

Game designers also like Google Docs to work with documentation, but it is difficult to keep documentation of a large commercial project in it.

I know teams that have devoted a lot of time to choosing documentation before development. They are rushing between Obsidian with its wonderful internal link system, a simpler and more versatile Notion. They even look towards the GitHub text editor. They want to have a knowledge base at hand at once, which can be maintained by several people at the same time. What do you think about it?

Konstantin: Attention to the means of working with documentation can protect against its loss or the long and unpleasant process of transferring materials from one system to another.

But the main thing, in my opinion, is not the system of working with documentation, but those plans, and the culture that is accepted in the team. On one of the small projects, we keep all the documentation in Google Docs (we even draw a Gantt chart in Google Tables).

An example of a document list for one of the author's games

Is it possible to say that a comprehensive design document and a knowledge base in general are documents about what has been done, and not about what needs to be done?

KONSTANTIN: In a way, yes.

The fundamental problem of any documentation is relevance.

The difficulty is not to write hundreds of pages of descriptions, technical specifications and formulas. It's not about coming up with and fixing it. The difficulty is not to miss any changes that were casually announced by the producer at the project meeting, the proposal of one of the team members that was accepted, the actual implementation adjustments made by the programmers in order to optimize.

If the documentation is not up to date, how can it be used to integrate new employees into the team? How can I test the functionality of the game using it? Then why is it needed at all?

You're talking about relevance now. There is always the problem of updating documentation. New features appear, old ones disappear… Plus, builds are constantly being rolled out for running-in. There are a lot of builds that can differ from each other by just a couple of modified digits. Does it even need to be fixed? And, in general, what should be included in the documentation and what should not?

KONSTANTIN: To answer this question, we need to remember that the documentation in game development is not only product documentation, which we usually talk about. When developing games, we often have to deal with administrative (which prescribes regulations, rules, staffing tables and department structures), legal (it deals with contracts, agreements, etc.) and project documentation. The case with builds is related to the latter.

Let's say we have a design document on the mechanics of loot boxes. In version 2.1.1, the loot box gave out no more than four items. From the next version, the number of items has become unlimited. This is a question for the composition of the build, which means it should be fixed in the project documentation.

At the same time, it is not necessary to store the entire update history in the design document. We are just updating the document, indicating how this or that mechanic works or should work now.

If in a couple of years the developer wants to return to the old balance, then in this case he should have a document management solution that has a version control system that allows you to find a version of the document for a certain date.

This is another important argument in favor of choosing specialized systems for maintaining game design documentation. It will be difficult to do this in Google Docs or MS Word. However, I have come across cases of using OneDrive and SVN to store documents.

Of course, it is also always important: Who should bring all this in? Should it be a separately paid position or is it the position of a producer or a "project"?

KONSTANTIN: Everyone has their own area of responsibility. Design documentation is controlled by game designers. And if it is not relevant, then the question should arise precisely to them — why.

Project documentation related to the deadlines, assembly processes, filling and verification of builds is most often prepared by the project manager and the head of QA.

The producer is responsible for his documents — the vision of the project and the composition of the version, for example.

It is good practice to be responsible for the document you have written. Who is the author is the one who monitors the relevance. But without built-in processes for informing the author about changes, such a model does not work well.

Let's go back to the beginning of our conversation. Let's imagine that the team has just started creating a game. What should be the documentation at the first stage of development, when the programmer has not yet sat down to code? What should be in it, and what can be ignored?

Konstantin: Short and clear. The larger your document, the less likely it is that it will be read to the end. The documentation does not imply discrepancies and double interpretations. In my classes, I always give an example of an ideal document that I have met in my life:

Everything is immediately clear: what needs to be done, what is not necessary, what will be the consequences, who is the performer…

All documentation at the initial stage of development should be primarily accessible and understandable to the reader.

One more thesis directly follows from this: there is no need to think out his work for the performer. Before describing the specifications, naming configs, variables, and prescribing other technical nuances of the implementation, talk to the programmer and agree on what it will be, what he needs to know about the feature in order to start working on it.

Of course, if your team has worked together for a long time and has already made more than one game, game designers understand well what developers need. But even in this case, there may be nuances related to the specifics of a particular project.

Is it worth starting work on the game at all with documentation? Maybe it's enough to agree on the structure of the gameplay on your fingers? They say, they figured out the basic mechanics in Miro, the bark cycle — and drove?

Konstantin: It's hard for me to imagine a game product that can be started without documentation. Moreover, until the moment when you need to write product documentation, you need to do a huge amount of work!

As a game designer, it is very difficult for me to write a design document without having market research and understanding of competitors, the target audience, and the capabilities of our team.

As the head of a studio or business, it is impossible for me to imagine starting work even without estimated financial documents. Yes, the timing, cost and mechanics of the product will definitely change during the implementation process. Most likely, for the worse. But without a basic understanding that such a game generally has a chance to recoup its cost, I would not risk taking the job at all.

What can we say about the ambiguity of interpretations! By drawing a gameplay diagram in Miro and giving it to the programmers, you will not get your prototype, but how the programmers saw and understood the task.

Yes, if we are talking about prototyping, then in some cases this is acceptable. Long-established teams, simple, for example, hyper-casual games…

But I always try to prepare complete documentation, regardless of the project.

It is often difficult to strike a balance between the perfectionism-filled desire to prepare comprehensive and verified documentation and the entrepreneurial zeal to do it inexpensively now. However, it is the balance that is necessary. I have not come across cases where these extremes would work well in commercial development.

Now we have touched upon the topic of programmers and their vision. Let's leave it at that, then. How do I work with programmers? Especially in the initial stages. I have come across situations where the task for them was formulated as vaguely as possible, almost limited only to the direction, and then the reins were "released." Is this a common practice?

KONSTANTIN: Unfortunately, this is more than a common practice.

The very fact that we do not have an accurate vision of the product at the initial stage is absolutely normal. A clear technical task can be written without searching only if we make a clone.

If we want to bring at least a little unique mechanics to the genre, I'm not talking about USP, we will always have ambiguity about how the product looks, plays and behaves.

Moreover, the producer may feel that he knows and sees the game for sure. But without real playtests, this is just a vision.

But this does not mean that we should not have an exact technical task and we ask the programmer to do "something like that". This means that we have a lot of technical tasks. We make one option, evaluate it, check with criteria, experience, feelings. If we understand that this is not the case, we write a new technical task and again in a circle.

There may not be a vision until some point, but the technical task should be.

It always seemed to me that if a game designer knows how to program, then this is a great success. He himself can file down the mechanics, immediately try it out, immediately throw it away or, conversely, decide that it is suitable. What should I do if a game designer can't do it? How to evaluate the invented mechanics, which exists exclusively in the form of a flowchart and a pair of tables in Excel?

KONSTANTIN: I try never to ask game designers to write code. In my opinion, there is a clear paradigm: a programmer writes logic and tools, a game designer creates a gaming experience.

It is important to adhere to this paradigm and keep it in mind: it is not the programmer who adjusts the sensations of the shot or places objects in the engine. The game designer does all the work with the content. He came up with how he wants the player to shoot, so he must adjust the weapon, understand its properties and count the balance.

The programmer's task is to provide the tools so that, without knowing C#, C++ or any other language, the game designer can customize the shots the way he wants.

As for self-assessment of gameplay, there is Unity Bolt, UE Blueprints, scripting languages JSON, XML, LUA, YAML for this…

Sometimes you can make a paper prototype - a desktop, sometimes you can assemble it yourself in simple engines like Buildbox or GameMaker. But many things can be typified only by involving programmers in the work.

A long time ago, when I wanted to show my ideas to the producer and colleagues, I made a prototype in Adobe Flash and animated it using Action Script. Therefore, I switched to HMTL5 and JS. This is a great way to save time and explain what you want to achieve from the team, but very often the mechanics cannot be evaluated without a full-fledged implementation, balanced content and visual component.

Let's imagine that we explained the mechanics to the programmer, he implemented it coolly… And then the question arises: at what point does mathematics, formulas, and balance come into the documentation? Do I need to think about them and take them seriously in the early stages of development?

KONSTANTIN: If you are serious corporate guys with some time and finances, you can afford to paint a good mathematical model from the very beginning, being aware that in the future it will still undergo changes. This is exactly what I'm sinning against and I'm having a hard time rebuilding from a corporate past to an indie developer approach.

If you are the indie, at the initial stage you often need a general understanding of what formulas will be used approximately. Sometimes it is even possible to replace precise and complex models with plugs (some of them will survive until release).

An example of a formula from the game Shadows of Vengeance

I'm a big fan of mathematics and plot, so I have to stop myself when I start working on balance tables or writing scripts.

But here's what you should definitely add to the product documentation at the earliest stage — examples of using mechanics. Let's say you're writing a large design document on spell mechanics. Show a couple of spells that you want to see in the game. Not a complete list, not a mathematically verified balance, but an example of the content that will be implemented on this mechanics.

Well, you can omit the math in the first stages, but what do you say about the screen fakes, which can help you understand what the game will be like when it is ready. Now, as far as I understand, this is a common practice. But are they really needed?

Konstantin: Fake screenshots are an important story. They are needed:

• to impress investors. This is a normal practice, because it is quite difficult to evaluate a potential product without visualization;
• for marketing, so that the team can test whether the chosen approach to graphics can interest the audience, is there a response;
• for internal use. In this context, I would call them target art. To develop the visual style of your product, it is very important to have a picture that suits us in terms of quality and reflects our production capabilities. For indie, this is not always relevant. As well as for those who have precisely decided on a style, a mudboard and work according to a ready-made guideline.

Accordingly, if we started to draw fake screenshots, is there a place in the documentation for a detailed description of the visual style, interface elements, all this, or is it better to throw examples, general wishes to the artist, and then finish the result?

Konstantin: Different studios have adopted different practices. When I worked for companies operating on large budgets, we compiled detailed documentation on art. In smaller studios, you can limit yourself to a mudboard presentation or a Figma board, which contains art from the web or AI—generated images reflecting our vision of the key assets of the game: characters, buildings, visual effects, interface elements, magic, materials, etc.

A fragment of the mudboard from the author's game

Let's imagine that our development has run ahead. The documentation is also decently swollen. What should I think /remember at this moment, what things should I pay attention to in her charge?

Konstantin: As we have already noted, first of all, the documentation must remain relevant.

Large projects often suffer from dozens of outdated articles, and only a game designer knows what to read and what to skip in this chaos.

To prevent this from happening, there must be rules for updating documentation and responsible people from whom you can ask.

At some point, it may be necessary to restructure the Confluence sections, which no longer reflect the sprawling structure of the project and have become inconvenient to navigate.

One of the key principles of maintaining corporate product documentation is the convenience of searching and reading above the convenience of writing.

There is another approach. When you are an indie team, it is often convenient to say OK, this document has completed its task, we transfer it to the archive and move forward.

And the last question: how much do you think the success of the project (in this case, bringing it to release) depends on competent documentation?

Konstantin: Games are a venture. Their commercial success depends on everything at once and on nothing in full. There is no documentation that guarantees success, just as there is no constitution that protects democracy.

As for bringing the project to release readiness, here the dependence on high-quality documentation is completely direct. And what is very important, not only the quality, depth of study and conciseness of documents play a role. The very process of working with documentation, instilling responsibility, is an extremely important part of development.

But as always, there are exceptions everywhere in game development. If you are an indie loner, incredible dedication is often more important than verified documentation, the only reader of which is often yourself.