Disdoc, or writing design documentation

  • Tutorial
Disdoc is mentioned in conversations, forums are whispering about it, and green beginners and experienced developers are looking for examples of it. It happens that a deal happens under the dim light of a street lamp. The figure in the dark hood stealthily transmits a link to "Revenge of the Ryaba chicken." Of course, the mysterious messenger does not have malicious intent, but the act was committed ...



Humanitarian dzdok


However, what is a “dzdok"? - the reader may ask. In a nutshell - this is a game written "on paper". Such a document is requested by all members of the development team. Here you can find a description of the gameplay mechanics, mathematical models of balance, a branched plot of the game, instructions to the musician, a list of sounds and visual effects ... At least this is what the “classic” examples of dzdokov teach us. The most famous of them in Russia is, of course, the document "Revenge of the Ryaba chicken" from the distant 2004. And here is another copy of the blank dzdoka, the other day I caught my eye on Reddit 'e.

As you can see, their structure is extremely similar - the document is intended simultaneously for everyone and for no one. It is written in the “technical humanitarian” language, which already loses its meaning for the programmer, but is still not well understood for the artist. In addition, the colossal size of the dzdoka leads to the complexity of navigation, reading, maintaining the text in a clean and up to date condition. You must be familiar with the term “information noise”; team members will fight precisely with this problem in search of the necessary information. If the grand master of game design of the 90th level is able to cope with the difficulties that arise, then think about the beginners, what kind of dzdok will they write?

On this stunning note, I would like to propose an alternative version of the dzdock, based on the granulation of documentation - it is divided into small, clear tasks so that the performer does not waste time searching and filtering information, but can immediately get to work. Someone will shout from the audience that the isolation of the task is a minus. And he will be partly right, because the performer does not see the big picture and works on his fenced site. It is here that gets a chance to shine with golden, polished to a brilliant mind His Management Project Manager.

He is able to convey to the team the current state of the project, to tell both about the difficulties that have arisen and about the successes that the developers have achieved. A lot of tools are hidden in his sleeve. One of them may be “agile”, but I will talk about this a little later. There, a little later, there will be links to my version of the project documentation.

Winter accidentally trending


Many months ago, I was fortunate enough to stumble upon a warm lamp adarkroom . After playing until morning and being late for work, I was inspired. Simple game mechanics and a complete lack of graphics served as a catalyst for the imagination revealed by the extravaganza of colors in the head. Thus was born the idea of ​​the project "Survive the Winter", a game with simple game mechanics and the presence of graphics. A number of circumstances, however, did not allow to begin full-fledged development, and the idea was abandoned in the chest of drawers.

For one wonderful lunch break, I came across a question asked on the forum. An inexperienced developer asked for an example of a dzdok, I wanted to figure out how to design a game. The responses of the regulars consisted mainly of meager attempts at trolling and references to "Ryaba's chicken revenge." That day the Idea was born. "Survive the Winter" is a fictitious mobile game; it is, as it were, but it is not. I decided to use the old concept, and on its basis to create open documentation on creating a game from scratch. “A bunch of files in Google Docs, a number of interface layouts, as well as a generous scattering of tasks and technical tasks in Trello can be a good example for both green beginners and experienced developers,” I thought elaborately, getting to work.

As the spiritual heir to the adarkroom game, Survive the Winter is a variation of the clicker. Recently, this genre is gaining more and more popularity. Colleagues in the online edition of Zuckerberg Calls wrote an article analyzing the current state, as well as the possible prospects for clickers.

Fictitious gameplay


"Survive the Winter" is based on the management of four resources: food and firewood in the warehouse, satiety and warmth. Accordingly, the player is required to go hunting in time, stock up on brushwood, eat and make a fire. At times, “events” occur. A window appears with the text: “Among the thickets of hazel, you noticed a hidden rabbit. With a habitual gesture you pull the bowstring. Fire?". After which the user decides what to do. For example, answering positively, he receives a message: “An arrow intended for deer hunting pierces a tiny animal’s body through and crash into a dry snag”, at the same time the hero receives +5 units of meat. These “events” can have a variety of consequences, starting with getting extra meat and ending with the hero’s injury (a debuff complicating the game). They gradually reveal the plot of the game.

At first glance, it may seem that the project is small and uncomplicated in development, even if you plan for a high production value (that is, exceptional product quality). But is it? Developers often underestimate the amount of work going into a small project by their standards. I believe that a game of the size “Survive the Winter” is a great way to achieve my goal - to show people another alternative example of dzdoka.

Large documentation of a small project


Frankly, I myself did not expect the documentation to grow so widely. Take a look at the complete list of tasks in Trello. Notice that horizontal scrolling is available there, opening new columns. I note that pre-production has already been carried out, that is, preliminary work, information search, research. This saves us most of the engineering and game design tasks. Now the bulk of the work lies on the shoulders of programmers. If the tasks from the preparatory stage remained on the board, then its size would be one and a half times larger.

The documentation is conducted using two services: Google Docs + Spreadsheets and Trello. Google Docs stores general documents such as a project descriptionor a list of features. There are also hidden technical tasks referenced by cards from Trello. Trello itself is used as a backlog, that is, a warehouse of all the tasks available for work. Having run a glance over Trello, any specialist can visually see the whole project, visually evaluate the progress of the team, but first of all, such a display is convenient for the manager. The manager, I note, can be either a producer or a programmer or any other responsible specialist if the size of the team is small.

If you work according to flexible methodologies, then under “sprints” you should create a separate board and transfer tasks from the “backlog” to it. As a result, it will be possible to visually evaluate both the general state of the project and the state of the current “sprint”. If the amount of work for your project is noticeably greater than for “Survive the Winter”, then a common “backlog” board may turn into a hindrance: all tasks will not fit, you will begin to get confused in them. We'll have to raise the task tracking service like Jira or Redmine. However, for most indie developers, Trello should be perfect. Otherwise, I recommend that you carefully examine the size of the project, is it probably too large?

Sprint, Agile, Backlog and other compound words.


Just in case, I’ll tell you a little about “sprints” and “agile” for those who have not yet met this trend in software development methodologies. Sprint refers to a short period of time, usually one or two weeks long. At the beginning of the sprint, the team holds a meeting and decides which tasks will be accurately completed in the allotted time. The key goal when choosing tasks is to get a specific working functional at the end of the sprint. Accordingly, during the final meeting, the team is shown a working demo, at this “sprint” is considered completed.

Sprint is also an excellent tool for maintaining motivation, because people work together to achieve a common goal, a working functional in a demo, encouraging each other, and by the end of the allotted time they get a tangible result, which is always nice. Moreover, even if one developer works on the game, sprints are still an excellent motivator: the developer does not “saw” some abstract code, but implements a specific game feature that can be felt directly in the game’s “build”. "Build", in turn, can be allowed to cuddle friends and acquaintances. Main board

structureTrello is convenient for general project management, but not suitable for sprints. It makes sense to take the tasks selected for the next “sprint” from the “backlog” board, which can be compared to a big bag with gifts, and transfer these tasks to a new, separate board, designed for one “sprint”.

I want to note right away (and sprinkle ashes on my head) that the “Survive the Winter” documentation in its current version resembles a waterfall model. This methodology is different in that all tasks are prepared in advance, and then transferred to the performers. The project moves on previously laid out rails, it becomes inflexible, it is difficult to make any changes - they literally crumble its rigid structure, threatening massive destruction, disruption of deadlines and going beyond the budget. I had to create just such a general board with tasks designed in advance and with special care, in order to visually show the developers the entire documentation, as if from a bird's eye view.

Distributed Disc


On the backlog, the cards are grouped by meaning and arranged in priority so that the most important ones are always in sight. You can go even further and group tasks by features. In other words, in order to have the feature “event” (remember, I was talking about a poor rabbit pierced through by an arrow?), We need to implement a pop-up window for it, take some text from somewhere, give buttons for selecting a response option for the “event”, and so on . That is, each individual feature has several tasks. Thus, the specialist will be able to see which task is associated with which, and what common goal they are combined. Therefore, it is important to create several specific documents that reflect each area of ​​the project, that is: programming, graphics, game design, sound and others. It turns out close integration with the principles of flexible development methodologies. Each feature is a functional designed “on paper”. At the same time, each sprint seeks to create a demo in which one-piece functional is implemented. In the end, everything serves to achieve a common goal.

The thorny path of a designer


You probably already clicked on tasks in Trello. In each you see a squeeze of information designed for a specific specialist. If he is a programmer, he receives more technical descriptions, if an artist - more descriptions of sensations ("the game should blow cold!"). Creating technical tasks for different specialists, one should strive to understand the type of their thinking, to know what is important for them and what is empty words. This should always be kept in mind. Documents must be created with high detail so that the specialist does not waste time thinking through and filling in the gaps for the designer. In the best case, this leads to frustration, in the worst it turns out that part of the work will then have to be redone.

Designing a game takes a lot of time; it is important not to fall into the trap, considering that the preparation of tasks and terms of reference is a quick process that can be dealt with as if between things. When creating technical tasks for a team, you have to deeply analyze the game, then break it into tiny pieces, giving them a clear and unambiguous description, so that the performer would be comfortable working on such a task. This is a long time. Doing this in my free time and on weekends, I had to spend about two months on “Survive the Winter”.

No less time is spent searching for information. Many tasks require preliminary preparation, research, filtering of information noise. For example, when creating a cross-platform mobile game, describing the technical task for the artist to draw icons for the application, you need to shovel weighty guides from the Apple, Android, Amazon and WP8 stores in advance (the most confused platform, a lot of icons and tiles, but the guide is literate). You cannot just throw links in the task; you need to go yourself and make a squeeze out of a ton of text, leaving the performer only the information important to him. Meanwhile, breaking the documentation into small but feasible tasks, it will be a good tone to tell the team where and what other information is available. After all, there are always interesting and important documents outside their separate tasks,

Final thoughts


The documentation is in a constant state of Work in Progress. This means that although the main work has been completed and a strong foundation has been laid, I want to develop and improve the project by adding new content and adding to existing ones. If you have any wishes or suggestions, I’m always glad to hear. This sample documentation is not the ultimate truth. The author admits that there are more advanced and flexible working methods, but there are no examples in the public domain. I propose my own version and call for discussion. Everyone is expected to benefit from this.

And again links to everything:


• Todo list in Trello.
All documentation in Google Docs.
• The document " Start here ", from which you can begin familiarization with the documentation.

Also popular now: