Как и зачем мы документируем проекты
Стиральная машина - источник вечных страданий и неразрешимых вопросов. Какую кнопку нажать? А если светлое вместе с темным, то это ничего? Зачем здесь столько отделений и почему рядом стоит столько коробочек и бутылочек? Что сделать, чтобы моя единственная и любимая футболка не села на 5 размеров, как в прошлый раз?
Можно пробовать взаимодействовать с устройством "методом тыка" (и иногда это работает), а можно прочитать инструкцию, из которой станет понятно, куда повернуть крутилку и что нажать, чтобы в итоге футболка осталась прежнего размера, но стала чистой.
Инструкции тем более полезны, чем более сложны устройства, к которым они написаны. На определенном уровне сложности устройства инструкция становится настолько же важным его атрибутом, как и устройство само по себе.
Инструкции можно писать не только к объектам физического мира, но и к любым другим сущностям, взаимодействие с которыми не очевидно, например, к Налоговой. Или к сайту.
Мы всегда пишем инструкции или, по-другому, составляем документацию на все проекты, принцип работы которых достаточно сложен и от того не очевиден. Документация обеспечивает удобство и экономит ресурсы как на короткой, так и на длинной дистанции.
Кому и зачем нужна Документация?
Во-первых, владельцу сайта и его сотрудникам
Чтобы знать, как добавить новый пост в блог, управлять заказами в интернет-магазине, регистрировать новых пользователей и т.д.
Чтобы не тратить свое время на обучение новых сотрудников и не зависеть от старых.
Если ваш сайт реализован на CMS (Системе Управления Контентом) и содержит исключительно "коробочный" функционал без каких-либо изменений, то документация к нему уже скорее всего готова, вот пример для CMS NetCat. Однако, в реальности для сколько-нибудь сложных и живых проектов всегда возникает новый, нестандартный функционал. Если взаимодействие с ним не очевидно, значит он должен быть описан подобным же образом.
Во-вторых, владельцу и программистам сайта
Чтобы знать, не только как запрограммирован сайт, но и почему именно так.
Как ни странно, именно вопрос "Почему?" самый каверзный, что объясняется следующими особенностями долгосрочной веб-разработки:
- Итерационный подход. В большинстве случаев развитие сайта или веб-сервиса - это постепенный поэтапный процесс. Сначала делается одна часть функционала. Потом другая. Потом подтягивается первая. Потом добавляется третья. И все они как-то связаны друг с другом. Редко когда веб-сервис делается сразу от начала и до конца, потому что Интернет развивается довольно динамично и чтобы соответствовать времени, сайты должны постоянно развиваться.
- Непредсказуемость. Никогда заранее неизвестно, как предстоит развивать сайт в будущем и как именно будут связаны друг с другом новые и старые функционалы.
- Забывание. Все забывают всё. В большинстве случаев все подробные детали разработки функционала полностью стираются из памяти примерно через 2 месяца. Не только из памяти программистов, но и владельца сайта. Поэтому, если через 4 месяца возникнет необходимость подключить новый модуль, ответ на простой вопрос "возможно ли это и сколько будет стоить" может превратиться в боль.
Итак, из-за этих особенностей в долгосрочной перспективе любой активно развивающийся веб-проект стремится погрузиться в хаос.
Больше всего это напоминает проектирование городского пространства и дорожной сети в нем (см. SimCity). Представьте, что вы Главный Архитектор и отвечаете за планировку деревни, стремящейся перерасти в город. Если пустить все на самотек и решать сиюминутные задачи, то на первых порах деревня будет развиваться очень динамично, но в среднесрочной перспективе возникнут проблемы. Дороги начнут упираться в дома. На нужных перекрестках не будет хватать места для развязок. Варшавское и Каширское шоссе десятилетиями будут разделены промзоной до самого МКАДа. Дальнейшее развитие будет становиться все более и более сложным и дорогим.
Ответственный Главный Архитектор начнет с того, что продумает:
- общие принципы развития своей деревни, определит основные магистрали;
- потенциальные цели и задачи: что может понадобится городу в будущем;
- застолбит зоны, которые запрещено застраивать на случай будущего расширения.
Продумав, он все это это запишет и получится Документация на Город.
Документация не панацея, но гарантия разумного подхода и заинтересованности разработчика в долгой и успешной жизни продукта. Только при ее наличии возможно грамотно оценить трудозатраты и стоимость разработки нового фукнционала, иначе сумму придется взять "с потолка". С самого высокого, на всякий случай.
Как мы документируем проекты?
При создании документации для конечных пользователей сайта, работает правило:
На практике это означает, что мы стараемся проектировать все интерфейсы так, чтобы работа с ними была очевидна и документирования не требовала. Если все же нужны пояснения, создаем подсказки прямо в самом интерфейсе, примерно вот такие: В случае необходимости объемных комментариев, создаем скрытый от внешнего мира раздел прямо на самом сайте.
При создании технической документации для обеспечения долгосрочного развития проекта, работает правило:
В первую очередь важно, чтобы документацию быть удобно писать, дополнять и обновлять, иначе лень погубит всю идею. Мы используем те инструменты, которые наиболее уместны в конкретном случае.
Для архитектурно не сложных и четко очерченных задачах мы иногда ограничиваемся разработкой прототипа интерфейса с комментариями, например с помощью https://moqups.com/ Посмотрите примеры в нашем портфолио, скриншоты из ТЗ внизу страниц:
Для более сложных проектов с перспективой дальнейшего развития документация обычно создается в виде вики-сайта - это самый подходящий формат. Для каждой сущности (т.е. модуля или функционала) создается отдельная страница с ее описанием, а система навигации на базе обратных ссылок позволяет удобно зафиксировать все взаимосвязи: что от чего и как зависит.
Несколько примеров:
При документировании каждой сущности мы стремимся:
- предусмотреть все наиболее вероятные потенциальные возможности ее развития и оставить необходимые "заделы" на будущее;
- зафиксировать принципиальные решения по архитектуре и причины их принятия описать простым словами, отвечающими на вопрос "почему сделано именно так, а не по-другому?";
- получить уверенность в том, что через полгода, проснувшись среди ночи, любой средний программист сможет прочесть это описание и понять принцип работы модуля и внести в него изменения и ничего не сломать при этом.
Вся информация сохраняется в едином месте. Один проект - один вики-сайт. Любое изменение проекта - это сначала update документации, а только потом внедрение. Никаких мучительных поисков ответов в почте/месседжерах/телефонах. Процесс техподдержки и развития проекта становится комфортным как для разработчика, так и для заказчика, экономит время и силы.
Когда мы начинаем проект с нуля, то документация вырастает из Технического Задания, которое также делается в вики-форме. Начинаясь с описания базовых сущностей и бизнес-процессов, документация в процессе разработки обрастает техническими подробностями, необходимыми для поддержки проекта в дальнейшем. Если же проект достался нам по наследству, то перед началом работы производится первоначальный аудит, в рамках которого и создается документация.
