Dizdok, or writing project documentation
Dizdok is mentioned in conversations, it is whispered about him on forums, and green beginners and experienced developers are looking for examples of him. It happens that under the dim light of a street lamp there is a deal. A figure in a dark hood surreptitiously sends a link to Revenge of Ryaba Chicken. Of course, the mysterious messenger has no ill intent, but the act is committed ...
However, what is "dizdok"? - may ask the reader. In a nutshell, this is a game written on paper. This document is addressed for information by all members of the development team. Here you can find a description of gameplay mechanics, mathematical models of balance, an extensive game plot, instructions to a musician, a list of sounds and visual effects ... At least, we are taught by "classic" examples of dizdok. The most famous of them in Russia is, of course, the document “Revenge of Ryaba's Chicken” from the distant 2004 year. And here is another copy of the blank dizdok, the other day I caught sight of Reddit .
As you can see, their structure is extremely similar - the document is intended for everyone and no one at the same time. It is written in “technical humanities” language, which already loses its meaning for a programmer, but is not yet clear enough for an artist. In addition, the enormous size of the dizdok leads to the complexity of navigation, reading, and maintaining the text in a clean and up-to-date state. You must be familiar with the term “information noise”; team members will fight with this problem in search of the necessary information. If the grand master of the game design of the 90th level can cope with the difficulties that arise, then think about the beginners, what kind of dizdok they write?
')
On this amazing note, I would like to offer an alternative version of dizdok based on granulation of documentation - it is divided into small, precise tasks so that the performer does not waste time searching and filtering information, but can immediately begin work. Someone will shout from the audience that the isolation of the task is a minus. And it will be partly right, because the performer does not see the overall picture and works on his fenced plot. It is here that His Leadership project manager gets a chance to shine gold, polished to the light of reason.
He is able to convey to the team the current state of the project, to talk about both the difficulties that have arisen and the successes that the developers have achieved. In his sleeve hidden many tools. One of them may be "Agile", but I will tell about this a little later. In the same place, a little later, there will be links to my version of project documentation.
Many months ago I was lucky to stumble upon a warm tube " adarkroom ". Having played till morning and being late for work, I was inspired. Simple game mechanics and the complete lack of graphics served as a catalyst for the imagination that was revealed by the extravaganza of colors in the head. Thus, the idea of ​​the project “Survive the Winter”, games with simple game mechanics and the presence of graphics, was born. A number of circumstances, however, did not allow starting a full-fledged development, and the idea was thrown into a chest of drawers.
During one fine lunch break, I came across a question asked on the forum. An inexperienced developer asked for an example dizdok, wanted to figure out how to design the game. The regulars' responses consisted mainly of scant trolling attempts and references to Ryaba's Chicken Revenge. The Idea was born that day. “Survive the Winter” is a fictitious mobile game; She seems to be there, but she is not. I decided to use the old concept, and on its basis 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 developers with experience,” I thought while starting to work.
As the spiritual heir to the adarkroom game, Survive the Winter is a variation of the clicker. Recently, this genre is gaining increasing popularity. Colleagues in the online edition of "Zuckerberg Call" wrote an article analyzing the current state, as well as possible prospects for "clickers."
“Survive the Winter” is based on the management of four resources: food and firewood in a warehouse, satiety and warmth. Accordingly, the player is required to go on the hunt in time, stock up with brushwood, eat and make a fire. Sometimes "events" occur. A window appears with the text: “Among the thickets of hazel, you notice a hidden rabbit. With a familiar gesture, you stretch the string. Fire?". Then the user decides what to do. For example, responding positively, receives a message: “The arrow intended for deer hunting pierces through the tiny body of the animal and crashes into a dry snag,” but the hero also receives +5 units of meat. These "events" can have a variety of consequences, starting with getting additional meat and ending with the hero's injury (a debuff that complicates the game). They gradually reveal the plot of the game.
At first glance it may seem that the project is small and simple to develop, even if you plan a high production value (that is, the exceptional quality of the product). But is it? Developers often underestimate the amount of work that goes into a small project by their standards. I believe that the “Survive the Winter” size game is a great way to achieve my goal - to show people another alternative example of dizdoc.
Frankly, I myself did not expect that the documentation will grow so widely. Look at the full list of tasks in Trello. Note that horizontal scrolling is available there, opening new columns. I will note that preproduction has already been carried out, that is, preliminary work, information search, research. This saves us from most of the design 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.
Documentation is conducted using two services: Google Docs + Spreadsheets and Trello. Google Docs stores common documents, such as a project description or feature list. There are also hidden technical tasks that are referenced by cards from Trello. Trello itself is used as a backlog, that is, a warehouse of all tasks available for work. Having looked through Trello, any expert can visually see the project entirely, visually assess 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 are working on flexible methodologies, then under the “sprints” you should create a separate board, and transfer tasks from the backlog to it. As a result, it will be possible to visually assess both the general state of the project and the state of the current “sprint”. If the amount of work for your project is noticeably larger than for Survive the Winter, then the total backlog can become a hindrance: all tasks will not fit, you will start to get confused. We'll have to raise the task-tracking service for the type of Jira or Redmine. However, for most indie developers, Trello should fit perfectly. Otherwise, I recommend to study the size of the project more carefully, is it probably too large?
Just in case, I’ll tell you a little bit about “sprints” and “agyle” for those who have not yet become acquainted with this trend in software development methodologies. By "sprint" is meant 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 executed exactly in the allotted time. The key goal in selecting tasks is to get a concrete working functionality by the end of the “sprint”. Accordingly, during the final meeting, the team is shown a working demo, this “sprint” is considered completed.
"Sprint" is also an excellent tool for maintaining motivation, because people work together to achieve a common goal, - working functionality in a demo, - encouraging each other, and by the end of the selected period of time they get a tangible result, which is always nice. Moreover, even if only one developer works on the game, the “sprints” are still an excellent motivator: the developer does not “cut” some abstract code, but implements a specific game feature that can be felt directly in the game’s build. "Build", in turn, can be given to cuddle with friends and acquaintances.
The structure of the main Trello board is convenient for general project management, but is not suitable for “sprints”. It makes sense to take the tasks chosen for the next “sprint” from the backlog board, which can be compared with a large bag with gifts, and transfer these tasks to a new, separate board designed for one sprint.
Immediately I want to note (and sprinkle ashes on my head) that the documentation “Survive the Winter” in its current performance resembles a waterfall model. This methodology differs in that all tasks are prepared in advance, and then transferred to the performers. The project moves along pre-laid rails, it becomes inflexible, it is difficult to make any changes - they literally crush its rigid structure, threatening with massive destruction, missed deadlines and going beyond the budget. I had to create just such a common board with tasks that were designed in advance and with special care in order to visually show the developers the documentation, as if from a bird's-eye view.
On the backlog board, the cards are grouped by meaning and arranged according to priority so that the most important ones are always visible. You can go even further and group tasks by features. In other words, to have the feature “event” (remember, I told about a poor rabbit pierced through with an arrow?), You need to implement a pop-up window for it, take text from somewhere, give buttons for choosing an answer option for an “event”, and so on . That is, each individual feature has several tasks. In this way, the specialist will be able to see which task is related to which, and to which common goal they are combined. Therefore, it is important to create several special documents that reflect each area of ​​the project, that is: programming , graphics, game design, sound, and others. It turns out a 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, which implements an integral working functionality. In the end, everything serves to achieve a common goal.
You probably already managed to click on the tasks in Trello. In each you see a squeeze of information designed for a specific specialist. If it is a programmer, he gets more technical descriptions, if the artist has more descriptions of sensations (“the game should be 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 need to be created with high detail so that the specialist does not waste time thinking up and filling in the blanks for the designer. At best, this leads to frustration, at 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 compilation of tasks and technical tasks is a quick process that can be dealt with, as it were, in between cases. When creating technical assignments for the team, one has to deeply analyze the game, then break it into tiny pieces, giving them a clear and unambiguous description in order to work on such a task the performer was comfortable. This is a long time. Being engaged in this in my free time and on weekends, I had to spend about two months on “Survive the Winter”.
Not 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 artist’s technical task of drawing icons for the application, you need to shovel the weighty guides from Apple, Android, Amazon and WP8 stores (the most confused platform, a lot of icons and tiles, but the guide is literate). You can’t just add links in the task, you have to go and make a squeeze out of a ton of text yourself, leaving only important information for the performer. Meanwhile, breaking up the documentation into small but doable tasks, it will be good practice to tell the team where and what other information is available. After all, there are always interesting and important documents outside their separate task, scheduled for the current sprint.
The documentation is in a permanent state of Work in Progress. This means that even though the main work has been done and a solid foundation has been laid, but I want to develop and improve the project, adding new content and finishing the existing one. If you have any suggestions or suggestions, always happy to hear. This example of documentation is not the ultimate truth. The author admits that there are more advanced and flexible methods of work, but there are no examples in the public domain. I offer my version and call for discussion. It is assumed that everyone will benefit from this.
• Task list in Trello.
• All documentation in Google Docs.
• The document “ Start here ”, from which you can begin to familiarize yourself with the documentation.
Technical dizdok
However, what is "dizdok"? - may ask the reader. In a nutshell, this is a game written on paper. This document is addressed for information by all members of the development team. Here you can find a description of gameplay mechanics, mathematical models of balance, an extensive game plot, instructions to a musician, a list of sounds and visual effects ... At least, we are taught by "classic" examples of dizdok. The most famous of them in Russia is, of course, the document “Revenge of Ryaba's Chicken” from the distant 2004 year. And here is another copy of the blank dizdok, the other day I caught sight of Reddit .
As you can see, their structure is extremely similar - the document is intended for everyone and no one at the same time. It is written in “technical humanities” language, which already loses its meaning for a programmer, but is not yet clear enough for an artist. In addition, the enormous size of the dizdok leads to the complexity of navigation, reading, and maintaining the text in a clean and up-to-date state. You must be familiar with the term “information noise”; team members will fight with this problem in search of the necessary information. If the grand master of the game design of the 90th level can cope with the difficulties that arise, then think about the beginners, what kind of dizdok they write?
')
On this amazing note, I would like to offer an alternative version of dizdok based on granulation of documentation - it is divided into small, precise tasks so that the performer does not waste time searching and filtering information, but can immediately begin work. Someone will shout from the audience that the isolation of the task is a minus. And it will be partly right, because the performer does not see the overall picture and works on his fenced plot. It is here that His Leadership project manager gets a chance to shine gold, polished to the light of reason.
He is able to convey to the team the current state of the project, to talk about both the difficulties that have arisen and the successes that the developers have achieved. In his sleeve hidden many tools. One of them may be "Agile", but I will tell about this a little later. In the same place, a little later, there will be links to my version of project documentation.
Winter, accidentally in trend
Many months ago I was lucky to stumble upon a warm tube " adarkroom ". Having played till morning and being late for work, I was inspired. Simple game mechanics and the complete lack of graphics served as a catalyst for the imagination that was revealed by the extravaganza of colors in the head. Thus, the idea of ​​the project “Survive the Winter”, games with simple game mechanics and the presence of graphics, was born. A number of circumstances, however, did not allow starting a full-fledged development, and the idea was thrown into a chest of drawers.
During one fine lunch break, I came across a question asked on the forum. An inexperienced developer asked for an example dizdok, wanted to figure out how to design the game. The regulars' responses consisted mainly of scant trolling attempts and references to Ryaba's Chicken Revenge. The Idea was born that day. “Survive the Winter” is a fictitious mobile game; She seems to be there, but she is not. I decided to use the old concept, and on its basis 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 developers with experience,” I thought while starting to work.
As the spiritual heir to the adarkroom game, Survive the Winter is a variation of the clicker. Recently, this genre is gaining increasing popularity. Colleagues in the online edition of "Zuckerberg Call" wrote an article analyzing the current state, as well as possible prospects for "clickers."
Dummy gameplay
“Survive the Winter” is based on the management of four resources: food and firewood in a warehouse, satiety and warmth. Accordingly, the player is required to go on the hunt in time, stock up with brushwood, eat and make a fire. Sometimes "events" occur. A window appears with the text: “Among the thickets of hazel, you notice a hidden rabbit. With a familiar gesture, you stretch the string. Fire?". Then the user decides what to do. For example, responding positively, receives a message: “The arrow intended for deer hunting pierces through the tiny body of the animal and crashes into a dry snag,” but the hero also receives +5 units of meat. These "events" can have a variety of consequences, starting with getting additional meat and ending with the hero's injury (a debuff that complicates the game). They gradually reveal the plot of the game.
At first glance it may seem that the project is small and simple to develop, even if you plan a high production value (that is, the exceptional quality of the product). But is it? Developers often underestimate the amount of work that goes into a small project by their standards. I believe that the “Survive the Winter” size game is a great way to achieve my goal - to show people another alternative example of dizdoc.
Large documentation of a small project.
Frankly, I myself did not expect that the documentation will grow so widely. Look at the full list of tasks in Trello. Note that horizontal scrolling is available there, opening new columns. I will note that preproduction has already been carried out, that is, preliminary work, information search, research. This saves us from most of the design 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.
Documentation is conducted using two services: Google Docs + Spreadsheets and Trello. Google Docs stores common documents, such as a project description or feature list. There are also hidden technical tasks that are referenced by cards from Trello. Trello itself is used as a backlog, that is, a warehouse of all tasks available for work. Having looked through Trello, any expert can visually see the project entirely, visually assess 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 are working on flexible methodologies, then under the “sprints” you should create a separate board, and transfer tasks from the backlog to it. As a result, it will be possible to visually assess both the general state of the project and the state of the current “sprint”. If the amount of work for your project is noticeably larger than for Survive the Winter, then the total backlog can become a hindrance: all tasks will not fit, you will start to get confused. We'll have to raise the task-tracking service for the type of Jira or Redmine. However, for most indie developers, Trello should fit perfectly. Otherwise, I recommend to study the size of the project more carefully, is it probably too large?
Sprint, agile, backlog and other difficult words
Just in case, I’ll tell you a little bit about “sprints” and “agyle” for those who have not yet become acquainted with this trend in software development methodologies. By "sprint" is meant 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 executed exactly in the allotted time. The key goal in selecting tasks is to get a concrete working functionality by the end of the “sprint”. Accordingly, during the final meeting, the team is shown a working demo, this “sprint” is considered completed.
"Sprint" is also an excellent tool for maintaining motivation, because people work together to achieve a common goal, - working functionality in a demo, - encouraging each other, and by the end of the selected period of time they get a tangible result, which is always nice. Moreover, even if only one developer works on the game, the “sprints” are still an excellent motivator: the developer does not “cut” some abstract code, but implements a specific game feature that can be felt directly in the game’s build. "Build", in turn, can be given to cuddle with friends and acquaintances.
The structure of the main Trello board is convenient for general project management, but is not suitable for “sprints”. It makes sense to take the tasks chosen for the next “sprint” from the backlog board, which can be compared with a large bag with gifts, and transfer these tasks to a new, separate board designed for one sprint.
Immediately I want to note (and sprinkle ashes on my head) that the documentation “Survive the Winter” in its current performance resembles a waterfall model. This methodology differs in that all tasks are prepared in advance, and then transferred to the performers. The project moves along pre-laid rails, it becomes inflexible, it is difficult to make any changes - they literally crush its rigid structure, threatening with massive destruction, missed deadlines and going beyond the budget. I had to create just such a common board with tasks that were designed in advance and with special care in order to visually show the developers the documentation, as if from a bird's-eye view.
Distributed dizdok
On the backlog board, the cards are grouped by meaning and arranged according to priority so that the most important ones are always visible. You can go even further and group tasks by features. In other words, to have the feature “event” (remember, I told about a poor rabbit pierced through with an arrow?), You need to implement a pop-up window for it, take text from somewhere, give buttons for choosing an answer option for an “event”, and so on . That is, each individual feature has several tasks. In this way, the specialist will be able to see which task is related to which, and to which common goal they are combined. Therefore, it is important to create several special documents that reflect each area of ​​the project, that is: programming , graphics, game design, sound, and others. It turns out a 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, which implements an integral working functionality. In the end, everything serves to achieve a common goal.
The thorny path of the designer
You probably already managed to click on the tasks in Trello. In each you see a squeeze of information designed for a specific specialist. If it is a programmer, he gets more technical descriptions, if the artist has more descriptions of sensations (“the game should be 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 need to be created with high detail so that the specialist does not waste time thinking up and filling in the blanks for the designer. At best, this leads to frustration, at 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 compilation of tasks and technical tasks is a quick process that can be dealt with, as it were, in between cases. When creating technical assignments for the team, one has to deeply analyze the game, then break it into tiny pieces, giving them a clear and unambiguous description in order to work on such a task the performer was comfortable. This is a long time. Being engaged in this in my free time and on weekends, I had to spend about two months on “Survive the Winter”.
Not 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 artist’s technical task of drawing icons for the application, you need to shovel the weighty guides from Apple, Android, Amazon and WP8 stores (the most confused platform, a lot of icons and tiles, but the guide is literate). You can’t just add links in the task, you have to go and make a squeeze out of a ton of text yourself, leaving only important information for the performer. Meanwhile, breaking up the documentation into small but doable tasks, it will be good practice to tell the team where and what other information is available. After all, there are always interesting and important documents outside their separate task, scheduled for the current sprint.
Final thoughts
The documentation is in a permanent state of Work in Progress. This means that even though the main work has been done and a solid foundation has been laid, but I want to develop and improve the project, adding new content and finishing the existing one. If you have any suggestions or suggestions, always happy to hear. This example of documentation is not the ultimate truth. The author admits that there are more advanced and flexible methods of work, but there are no examples in the public domain. I offer my version and call for discussion. It is assumed that everyone will benefit from this.
And once again links to everything:
• Task list in Trello.
• All documentation in Google Docs.
• The document “ Start here ”, from which you can begin to familiarize yourself with the documentation.
Source: https://habr.com/ru/post/257603/
All Articles