Документация устаревает в момент ее написания

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

Многие привыкли работать шаблонами, которые тяжело нарушить, и которые довольно плотно укоренились в головах. С одной стороны, шаблоны - это просто и удобно, с другой, мы пишем однотипные тонны текста, которые никому не важны.

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

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

Даже фичи, которые мы писали в начале, к концу проекта в 90 процентах случаев будут изменены, некоторые выкинуты за ненадобностью и так далее.

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

Основная наша цель на любом этапе разработки -  максимально гибко работать со всеми нашими возможностями, и иметь шанс в любой момент изменить направление или выпустить проект как есть. Для этого мы используем итеративный процесс в написании документации, который выглядит следующим образом:

• пишется one page document или же pitch, который отвечает на основные вопросы и на основе которого принимается решение о том, будет ли делаться проект;
• на основе питча пишется расширенная концепция, которая покрывает вопросы об основных механиках, которые мы будем использовать;
• после этого весь проект разбивается на промежуточные этапы для реализации этих механик;
• на основе этого создается дальнейшая документация, которая покрывает конкретно и детально те фичи, которые мы будем реализовывать на ближайшем промежутке.

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

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

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

Что мы имеем в сухом остатке:

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

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