Почти все материалы на тему написания хорошего ГДД сводятся к советам в отношении одного документа. Но написать один хороший документ – это совсем не сложно. Сложно – это система документов для разработки, в которой количество документов растет, а содержание периодически меняется.
Артем Волков у себя в блоге написал статью “Clean Design Documentation Principles” про применение архитектурных принципов программирования при написании геймдизайн документации (название статьи – отсылка к книге “Clean Code: A Handbook of Agile Software Craftsmanship”). Это правильная и интересная мысль. Программисты десятилетия сталкиваются с аналогичной проблемой. Нетрудно написать код, трудно поддерживать, масштабировать и тд. Программист больше времени тратит на чтение кода, чем на написание нового.
В языке программирования Python есть манифест “The Zen of Python” описывающий подходы, применяя которые, скорее всего ты получишь, как минимум, сносную архитектуру. На мой взгляд, эти принципы отлично подходят для создания понятной, удобной, прозрачной , готовой к расширению системы ГДД.
Я использую эти принципы при работе с ГДД. Если их соблюдать, получаются и отличные документы и система в целом. Понятная, удобная, способная к прозрачному использованию и расширению.
Beautiful is better than ugly. Readability counts
ГДД должно быть сделано с любовью к тем, кто его будет читать. Структурированное, с отступами, заголовками, списками, понятными таблицами, схемами, идти от главного к частному, кратким и емким. Перед тем, как отдать ГДД, нужно 3-5 раз его перечитать и улучшить. С документом должно быть приятно работать. ГДД – это не поток сознания, это чертеж, в нем нет места помаркам и кофейным пятнам.
Explicit is better than implicit
Пишите не только “как”, но и “почему”. Понимание причин тех или иных решений или выборов, может дать человеку возможность улучшить решение или реализовать его другим, более лучшим способом.
Плохой пример – “при взлете камера должна отъезжать”. Хороший пример – “при взлете камера должна отъезжать, я хочу добиться эффекта динамичности, показать ускорение”. Во втором варианте команда может предложить вам “а давай тогда еще и motion blur сделаем, чтобы усилить твою идею”.
Simple is better than complex. Complex is better than complicated
Описывайте идеи настолько просто и настолько простым языком, насколько это возможно. Не каждый в вашей команде может понимать узкоспециализированные термины. А еще хуже, когда кто-то будет понимать их по другому.
Плохой пример – UX дизайнер попросил помощи у 2d художников в создании иконок абилок и использует слова “аффорданс”, “консистентность”. Художники в итоге не понимают эти места в ГДД и просто игнорируют их. Хороший пример – UX дизайнер использовал слова “должна выглядеть так, чтобы было понятно, что по ней можно кликнуть”, “стилистика не должна выбиваться, вот ссылка на библиотеку других элементов”.
Flat is better than nested
Любые определения, значения и тд должны встречаться только в одном месте. Во всех остальных местах, где необходимо упоминание, нужно ссылаться. Это позволяет избежать проблем с внесением изменений на этапе роста количества и связей ГДД.
Плохой пример – время перезарядки указали и в ГДД на оружие, и в задаче в JIRA. Через несколько недель в ГДД время поменяли, в задаче конечно же не поменяли. В итоге QA проверяло “как в задаче”. Хороший пример – указать в задаче “параметры смотрите по ссылке”.
Sparse is better than dense
ГДД не должно пытаться вместить в себя все и сразу. Дробите документы достаточно, чтобы они описывали один важный элемент игры, но не стоит спускаться на уровень атомарности.
Плохой пример – один документ описывающий одновременно систему кланов, матчмейкинга между кланами и миграцию старых данных. Получится огромное полотнище текста. Команда арта, которая будет читать документ, чтобы понять, что им нужно по фиче делать, начнет пропускать места, которые написаны “для программистов”, но вместе с тем пропустит и нужные места. Хороший пример – разбить документ на несколько, сделав ссылки друг на друга.
Changes should never pass silently
В оригинале стоит слово “Errors”, я заменил его на “Changes”. Имеет ввиду, что команда должна получать уведомления о любых изменениях в ГДД. А вносить изменения в ГДД может только ответственный за эту фичу.
Плохой пример – другой дизайнер внес изменения в ГДД, но рассказал об этом только программистам. Художники не узнали важную инфу, меняющую требования к их работе. Хороший пример – другой ГДД попросил владельца фичи внести изменения. После внесения изменений вся команда фичи получила автоматические уведомления, а дизайнер рассказал им смысл и причины изменений.
Namespaces are one honking great idea
С самого начала начните придерживаться единой терминологии во всех ГДД, задачах, обсуждениях и тд. Это упрощает общение и спасает от ситуаций, когда “понял, да не то”.
Плохой пример – программисты называли фичу “ранги”, а ГДД называли ее “лидерборд”. В итоге, когда программисты упомянули “ранги съезжают по срокам” ГДД не поняли, что речь про “лидерборд”. Хороший пример – все заранее договариваются и следят за неймингом.
If the implementation is hard to explain, it’s a bad idea. If the implementation is easy to explain, it may be a good idea
Если вы не можете выразить свою идею просто, скорее всего она плохая. Если можете, есть шанс, что она хорошая. У всех инструментов коммуникации (ГДД один из таких) есть одна и та же долина смерти – понимания. Пока вашу мысль не поняли, ее не могут ни обсудить, ни реализовать, ни оценить и тд.
Плохой пример – “вы не понимаете мою идею”. Хороший пример – “я не смог объяснить своей команде. Может я и опытнее, а они должны такое понимать, но они не понимают и другой команды у меня нет.”
Now is better than never
Не забивайте на актуализация документации. В Agile манифесте есть мысль про то, что “продукт, важнее документации”. Это правильная мысль. Но многие читают ее как “документация не нужна”.
Плохой пример – во время итераций дизайнер понял, что скорость перезарядки нужно увеличить и увеличил, а в документацию не внес с мыслями “это только мне нужно, я не забуду”. QA нашли расхождение, завели баг, программисты сделали “как в документации”. Обновление дизайнера в игру не попало. Хороший пример – внести изменения в игру, обновить документацию.
Although practicality beats purity
Но и гнаться за идеальным ГДД – глупо. Умение выдерживать баланс – то, что отличает опытного от новичка.
Плохой пример – еще вчера ГДД был нормальным и можно было отдать в разработку. Но дизайнер еще 3 дня доводил его до совершенства. Хороший пример – отдал документ сразу, но получив фидбек, внес пару правок.
Special cases aren’t special enough to break the rules.
Не стоит делать исключения, даже если кажется, что ваш случай особенный.