Пользователь
0,0
рейтинг
6 декабря 2011 в 21:32

Разработка → Как создать ТЗ для программиста из песочницы

Рекомендации геймдизайнеру от программиста (архитектора).


Вступление

Компьютерные игры — относительно молодая отрасль, которая в перспективе сменит киноиндустрию, так-же как кинофильмы заменили театр. Создание игры — это коллективное творчество, во многом напоминающее создание кинофильма. Кроме того, создание компьютерных игр — одна из самых сложных IT задач, поскольку она включает все себя практические все IT области.

Все слышали про pre poduction, но мало кто знает как именно это происходит. И если про стадию разработки написано много, а про стадию издания — еще больше, то про стадию планирования известно очень мало. В лучшем случае вам посчастливится ознакомится с результатами планирования. А вот как были достигнуты эти результаты? — загадка во тьме.

Этот документ является результатом «разбора полетов» после написания игры Звездная арена для социальных сетей. В этом документе я попытался упорядочить список проблем и решений к которым я и Александр пришли в процессе совместной работы над игрою. Кроме того этот документ является частью большой работы по выстраиванию рабочего процесса создания компьютерных игр.

Я намеренно оставил за кадром другие документы: концепцию, экономическое обоснование и ТЗ для других исполнителей. Это позволило сфокусироваться на одной теме и осветить ее и только ее достаточно подробно.


Самое важное:

  1. Четкое понимание конечного результата. (Контроль качества.)
  2. Сроки исполнения.


Зачем нужна документация:

  1. Экономия времени на коммуникациях. (Один раз написать, вместо того чтобы 100 раз пересказывать, путаясь в показаниях.)
  2. Способ увидеть, как будет выглядеть готовый проект.
  3. Анализ и выявление проблем еще на стадии планирования. (Чем раньше будет выявленна архитектурная ошибка — тем дешевле ее исправить)
  4. Фиксирование принятых решений. (Точные данные, вместо разрозненных слухов разной степени свежести.)
  5. Планирование работ.


Какие бывают документы:

  1. Концепция («Про че игра?»)
  2. Спецификация (Что мы хотим получить?)
  3. Техническое задание (Как это устроено — именно о нем будет идти речь.)
  4. План работ (Как мы это будем делать.)


Кто участвует в обсуждении ТЗ:

Чем раньше будет получена обратная связь от заинтересованных специалистов — тем меньше будет сделано лишней работы.
  1. Геймдизайнер (Написание документации)
  2. Архитектор (Отслеживание полноты и подробности описания, декомпозиция.)
  3. Программист (Оценка объемов работ.)


Требования к оформлению документации:

Чем более неряшливо будет оформление — тем меньше людей вообще начнет это читать. Читатели проявляют невероятную изобретательность, чтобы избежать неприятной для них работы. Поэтому так важно прилагать усилия к тому чтобы чтение документации было легким и приятным настолько, насколько это вообще возможно.
  1. Форматирование. (Легко напечатать и приятно читать/держать в руках)
  2. Выделение ключевых фраз. (Для чтения документа по диагонали)
  3. Составление списков. (Вместо сплошного текста)
  4. Разбиение длинных списков по группам. (По три пункта в группе)
  5. Многократные повторения. (Избегать ссылок по документу)
  6. Дата, номер страницы, количество страниц, нумерация пунктов. (Для точных ссылок при обсуждении прочитанного)
  7. Оглавление, список документов, история изменений. (Для поиска по документации/версиям)


Требования к содержанию ТЗ

Нет четкого списка требований, которому должна удовлетворять документация. Поэтому разработка ТЗ приостанавливается задолго до приближения к ее полноте. В итоге следующий этап разработки начинается без ТЗ, в надежде, что ТЗ будет дописана по ходу, или даже по итогам разработки.
  1. Русский язык. (Никаких мемов, искаженных аглийских терминов, албанского языка и прочего мусора. Даже внутреннюю документацию читают очень многие.)
  2. Никаких общих слов типа:
    • все возможные варианты
    • карта придумывается компьютером
    • взаимодействие различных объектов
    • после всех действий и т.д.
  3. Все названия видов сущностей(классов) должны иметь:
    • русское название (для игрока)
    • английское (для кода)
    • краткое описание (расшифровка/подсказка/комментарий)
  4. Сущность должна иметь только одно название. (Чтобы “броня” не превращалась на другой странице в “армор” или “щит”).
  5. Предложения должны быть полными и понятными читателю без пристального изучения контекста. (Не надо подразумевать, что читатель сам догадается до того, что подразумевал автор)
  6. Все что можно измерить, должно быть измерено.
    • размеры картинки в пикселях и байтах
    • количество столбцов и клеток в таблице
    • количество символов в текстовом поле
    • количество оружия на уровень
    • время сессии и т.д.


Главные требования к результату работы программиста:

Эти важные требования подразумеваются, но никогда никем не озвучиваются.
  1. Гибкость системы к изменениям. (Динамические требования.)
  2. Автоматический сбор данных об ошибках. (Обратная связь.)
  3. Простота запуска и настройки заказчиком. (Демонстрация результата.)


Первый этап написания ТЗ:

Описание предметной области, ее формализация в понятных программистам терминах.

  1. База данных (метаданные)
    • список типов объектов
    • характеристики объектов
    • связь/зависимость между объектами
  2. Бизнес-процессы (полный игровой цикл)
    • список процессов (сценарии работы)
    • список функционала (что должен уметь)
    • список ожидаемых изменений (что вообще может быть)


Второй этап написания ТЗ:

Как должен выглядеть/работать продукт для всех типов пользователей (игроки и администраторы).
  1. Интерфейс (визуальная часть)
    • список экранов игры с названиями (или группы элементов)
    • список элементов на каждом экране с названиями и текстом подсказок
    • описание поведения элементов (подмигивание, подсказка, блокирование, всплывающие диалоги и т. д.)
  2. Админка (управление)
    • сервер (жизненные/системные показатели )
    • игровой контент(распродажи, квесты, монстры, вещи, магазины, дроп, локации и т.д.)
    • игровые данные(контент генерируемый игроками)
    • статистика и отчеты (какую статистику нужно собирать?)


Третий этап написания ТЗ:

Как мы собираемся это все делать.

  1. Исследование необходимых технологий
    • Список требований к каждой технологии
    • Описание тестов/демонстрации работы каждой технологии
    • Список будущих требований/возможных проблем (что дальше?)
  2. Список требований к разным видам контента(ресурсов) для игры (размеры картинки мечей, длинна названий квестов, разновидности спецэффектов, размеры видеороликов и т.д.).
  3. Список небходимых инструментов для работы с контентом (редактор карт, админка квестов, ).
  4. Расстановка приоритетов по задачам.
  5. Требования к первой работающей сборке (что должен уметь первый прототип).
  6. Список остальных итераций разработки проекта с требованиями к их результатам. (Что нужно показать в конце каждого этапа, чтобы закончить его)


Сопровождение документации

  1. Большая часть того, что написано на первых этапах – устареет и будет нуждаться в переписке заново задолго до окончания планирования.
  2. Главный принцип первых этапов планирования: расставить список разделов и составить список вопросов по каждому разделу.
  3. Чем ниже детализация на начальных этапах – тем лучше. (количество типов оружия, вместо полного списка с названиями, количество квестов по уровням, вместо их подробного перечня и т.п.)
  4. Чем легче найти нужный пункт в документации и изменить его, не затрагивая остальное – тем лучше. Поэтому нужно избегать графических схем и сплошного текста из сложноподчиненных предложений. Оставьте графические презентации и эмоциональные описания для финальной отчетности.
  5. После каждого цикла планирования — проверять и тестировать полноту документации и равномерность уровня ее детализации. (Если в доме из 5 комнат описана только одна – нужно описать остальные четыре, или выкинуть подробное описание одной комнаты, чтобы все комнаты были описаны одинаково подробно.)
  6. Составить список неудобных вопросов. Темные пятна всегда есть, и их стараются обойти и замолчать, не осознавая этого.
  7. Предоставлять краткие инструкции конечным исполнителям. Конечные исполнители не должны сталкиваться с полной документацией, и мучительными поисками нужного упоминания по всему объему.
  8. Признак мастерства: каждый следующий уровень планирования уточняет, но не изменяет результаты описания более абстрактных уровней. Именно хороший навык перемещения по уровням абстрагирования/детализации позволяет перейти от припадочного описания деталей к планомерному перечислению сущностей.


Срезание углов

Любая технология будет упрощена до абсурда, чтобы уменьшить количество работы и расходов. Хлеб из химических дрожжей, вино из спирта, разработка без документации.
Многие считают что документация не нужна, если:
  1. Проект в 2-3 месяца.
  2. Команда из 2-3 человек.
  3. Ограниченный бюджет. (Он всегда ограничен)
  4. Нет требований к документации. (Никто не знает как надо делать)
  5. От нее нет никакой пользы. (Никогда не использовали документацию)

Однако следует помнить: разработка документации занимает 40% всех усилий. И определяет на 90% вероятность успешного завершения разработки проекта.

Первые шаги

Настоятельно рекомендуется новичкам выбирать в качестве первых проектов «клоны» классических игр. Пока нет успешного опыта такой игры — нет виденья всего цикла разработки продукта. А значит нет понимания того, как дойти до финиша.
Не стоит начинать разработку игры, не написав хотя бы двух полноценных ТЗ в качестве упражнения. Это может быть ТЗ по арканоиду. Но это обязательно должен быть ТЗ по которому разработчики смогут написать полноценный арканоид, даже если они никогда не видели этой игры прежде.
Евгений Павлов @BloodJohn
карма
26,2
рейтинг 0,0
Реклама помогает поддерживать и развивать наши сервисы

Подробнее
Спецпроект

Самое читаемое Разработка

Комментарии (50)

  • +2
    А почему статья названа «для программиста»?
    Для команды — да. Но не для программиста.
    • +1
      Потому что задания для других участников команды — оставлены за кадром.
      • +1
        Интерфейс (визуальная часть) — не программеру, а дизайнеру.

        Третий этап написания ТЗ — вообще не работа программиста.

        Сопровождение документации — а тут прогеры при чем?

        Все остальное — по сути общая инфа для команды. Но не полная т.к. рассмотрена лишь часть документации.
        • +1
          Статья написана для геймдизайнера. Не для программистов.

          Подразумевается, что геймдизайнер занимается разработкой и сопровождением проектной документации.

          Статья именно о плане работ для pre production стадии.
          • 0
            в том и прикол. задач для прогера в описанной документаци практически нет.
            • 0
              а они самые главные
  • +7
    Кажется, в тексте статьи не хватает полужирного начертания.
    • 0
      Возможно. =)

      Выделение жирным упрощает чтение текста по диагонали.
      • +6
        Вы, возможно, удивитесь, но статья — не ТЗ, и писать ее следует по несколько другим правилам.
        • –4
          Ага, гусиным пером и от руки, как писали лучшие авторы: Пушкин, Толстой, Достоевский. Почему бы не использовать современные возможности для достижения выразительности. Жирный шрифт не только упрощает чтение по горизонтали, но и заостряет внимание на важных с точки зрения деталях, которые могут быть упущены или посчитаны незначительными чтецом. В разговоре мы используем интонацию, паузы, жесты, почему стоит от этого отказаться при печати статей?
          • +2
            Проблема не в том, что вы используете выделение — просто не следует им злоупотреблять. Также следует разнообразить его — кроме полужирного начертания есть и курсивное.
            • 0
              Если уж серьезно к делу подходить, то каждое начертание для своей цели. Например, названия элементов интерфейса всегда выделяются жирным, а примеры текстовых сообщений — жирным курсивом.
              • 0
                Вы можете показать пример такого оформления?
                Есть список формальных правил для оформления?
                • 0
                  Я специально написал — «например». Каждая организация выбирает свой стиль исходя из поставленных задач.

                  Есть на эту тему и ГОСТы, но название/номер что-то сразу не найти.
                  • 0
                    ГОСТ 19.106-78 Требования к программным документам, выполненным печатным способом.
                    • 0
                      Спасибо :)
                      • +2
                        Не за что ;)

                        Интересно, будет ли актуальна тема про использование ГОСТов в IT-среде (и вообще разбором, какой ГОСТ для чего) с обзором программ для составления документации?
                        • 0
                          Да. Было бы очень интересно почитать!
                        • 0
                          Многим будет полезно :)
                        • +1
                          постараюсь в ближайшие дни подготовить и опубликовать :)
                  • –2
                    ГОСТ который последний раз пересматривался в 81 году, который предназначался совсем для других технологий и в других рабочих условиях.

                    Может еще берестяную грамоту обсудим?
                    • +2
                      Я с удовольствием поговорю и о берестяных грамотах, но читатели могут не оценить такой темы на Хабре :)

                      ГОСТ может и не вчерашний, но действующий. Если вам доведется работать над серьезным проектом в государственной сфере или в другой ответственной сфере (энергетика, транспорт и так далее), от вас скорее всего потребут документацию, соответствующую именно ЕСПД (ГОСТ серии 19). Так что тема ничуть не устарела, хоть ГОСТ и не менялся 30 лет.

                      Не говоря уж о том, что ГОСТ позволяет очень гибко менять и структуру документов и их оформление в зависимости от задачи, решаемой в данный момент.
                      • –1
                        Я не хочу обсуждать совсем другую сферу с другими уровнями риска и другими маштабами работы.

                        Речь о разработке игр. Здесь это не работает.
                        • +1
                          Почему не работает? ДАМ предложил разработать российский аналог WoW… Скорее всего, это будет гос.контракт. И там, скорее всего, в требованиях как раз-таки будет пункт про соответствие документации ГОСТ 19-й серии.
                          Вообще, ГОСТ — не так страшно и «бородато». Попробую в статье про это рассказать :)
                          • 0
                            П.С. а где 19, там и до 34-й серии недалеко. Хотя отличаются не сильно: 19 — программы, 34 — автоматизированные системы. Думаю, что тут будет ближе даже 34-я серия.
                          • 0
                            С нетерпением ждем статьи =)
            • +1
              Получается еще более пестро. Я за минимизацию количества стилей в одном документе.
        • 0
          Согласен с Вами.

          Моей целью было продемонстрировать стиль оформления ТЗ. Я посчитал что так будет гораздо полезнее для понимания смысла.
    • 0
      Это сео оптимизация текста :)
  • +2
    >Концепция («Про че игра?»)
    Возможно стоит исправит на «Про что игра?»
    • 0
      Долго думал, но решил оставить как шутку. (поэтому и кавычки)
      Один из самых сложных вопросов обычно задается именно в таком стиле.
      • +4
        Ладно, видимо у меня плохое настроение.
  • +1
    «Поэтому так важно прилагать усилия к тому чтобы чтение документации было легким и приятным настолько, насколько это вообще возможно.»

    Да, да и еще раз да! :)
  • +1
    Это все замечательно, если есть кому занимать и кто замотивирован это поддерживать :)

    Но, с точки зрения обоснованности тратить время и ресурсы на документацию, планирование и архитектурная проработка должны уменьшать ошибки и проблемы во всем проекте. Но с этой точки зрения прототип конечного результата намного эффективнее.

    В результате, на своих проектах, я создавал прототип ( корявый, все в заглушках, но функциональный ) без документации в команде из 2-3 человек, которые полностью владели всеми деталями проекта, и уже после того как по прототипу одобрялось все важное — писалась дока и так далее.
    • 0
      Твой случай как раз из «срезания углов»:
      1) геймдизайнер вместо написания документации умеет программировать.
      2) команда в 2-3 человека уже существует до запуска проекта в производство.
      3) минимальный жизненный цикл (прототип) — экстремально простой и короткий.

      В моем случае ни один из этих пунктов не выполнялся.

      Поясни пожалуйста, что ты подразумеваешь под «одобрением всего важного»?
      Лучше на конкретных примерах, если не сложно.
      • 0
        одобрением всего важного

        уточнение важных деталей ТЗ у стекхолдеров
        • +1
          Именно ради таких как ты в требованиях к ТЗ я первым пунктом написал требование избегать искаженных английских терминов.

          Руглиш — это плохо. :)
          • 0
            ну переведите, попробуйте :)
            • 0
              «у лидеров»?
              • 0
                Вообще PMI переводить это как «Заинтересованная сторона», но обычно это понимают неправильно, имея в виду стороны контракта или что-то типа того.

                Да «лидеры» тут совсем не при делах :)
                • 0
                  Стыдно не знать русского языка до такой степени.
                  • 0
                    1. Почему это стыдно?
                    2. До какой степени?

                    Я все еще жду вариантов адекватного перевода :)
  • +1
    К сожалению, тезис
    «Чем легче найти нужный пункт в документации и изменить его, не затрагивая остальное – тем лучше»
    противоположен другому тезису:
    «Многократные повторения. (Избегать ссылок по документу)».

    Не раз сталкивался с тем, что при внесении очередного минорного изменения становится лень прочёсывать весь документ и копировать правки по всему тексту.
    • –1
      Попробуйте новую функцию в текстовых редакторах: поиск в тексте по ключевым словам. :)
      • +1
        Не смешно и не конструктивно. Если вы так делаете — значит, ваша документация плохо организована.

        Вот способы сказать разными словами об одном и том же: «уникальное значение», «не должно повторяться», «используется как первичный ключ», «является потенциальным ключом», «встречается только один раз» и т. д. Перебирать в Ctrl+F все возможные синонимы ключевого слова — это крайне непродуктивно.
        • +1
          Вы правы. Проблема с обновлением есть.

          А моя документация — это не сад камней, а скорее обломки дома после урагана. Слишком мало ресурсов на нее выделено (все-таки это стартап) и слишком быстро растет энтропия в процессе разработки.
          Именно поэтому я и написал эту статью — как бороться с энтропией и что такое красивая документация.

          На мой взгляд выход как раз тех правилах, которые я выработал по названиям объектов.
          Уже на этапе планирования можно выработать стратегию имен сущностей, пока все имена находятся рядом в одном списке, а не разбросаны по разным документам.

          Я специально подчеркнул, что одна и та-же сущность должна иметь постоянное название по русски и по английски. (очень часто путаница возникает при переводе)

          Английские имена для кода, вообще не меняются и не склоняются — это одно из требований кода. По ним вполне удобно искать все упоминания в тексте.
          • 0
            Я тоже вот захотел спросить «Как Вам удаётся совмещать требования этих двух пунктов».

            Вы хотите сказать, что каждый раз упоминая объект по русскому наименованию, вы рядом упоминаете его по английскому несклоняемому имени? И наверно держите в документе ещё и словарик / алфавитный указатель?

            Если объект нагруженный, то его упоминания могут быть во множестве и в огромном количестве разных контекстов. Когда один из контекстов поменялся, прочёсывать все его упоминания даже с фиксированным именем может стать напряжным.
            • 0
              Нет, не хочу.

              Просто Вы намеренно искажаете написанное в статье до абсурда.
              • 0
                Если честно, даже не думал ни доводить до абсурда, ни даже наезжать на Вас. Просто имею аналогичные представления о качестве текста и соответственно аналогичную проблему. И пока её не решил для себя. Думал, мож Вы что-то придумали или узнали…
                • 0
                  Когда становится понятно что объект достаточно нагруженный — ему выделяют оттдельный документ-файл. В этот файл дописываются все ссылки на другие документы-контексты.

                  Высокая нагруженность одного класса — это явный признак плохой декомпозиции и будущее проблемное место в коде. Обязательно ведутся дополнительные исследования предметной области, чтобы прояснить этот сложным момент.

                  Никаких особых словариков не ведется. В роли словариков выступают списки классов.

                  Актуальность связи между классами-документами не отслеживается. Вместо этого выработанные правила/требования применяются при случайной ревизии отдельного документа, чтобы оценить его полноту. Если указанны не все связи — документ определенно не полон.

                  Хорошая политика именований позволяет сделать навигацию между классами интуитивно понятной.
                  3 варианта названий одного класса как раз и помогают нащупывать правильную стратегию именований. Это бывает не просто.

Только зарегистрированные пользователи могут оставлять комментарии. Войдите, пожалуйста.