Как и зачем мы документируем проекты

Стиральная машина - источник вечных страданий и неразрешимых вопросов. Какую кнопку нажать? А если светлое вместе с темным, то это ничего? Зачем здесь столько отделений и почему рядом стоит столько коробочек и бутылочек? Что сделать, чтобы моя единственная и любимая футболка не села на 5 размеров, как в прошлый раз?

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

Использование инструкций - это пример разумного подхода к жизни

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

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

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

Кому и зачем нужна Документация?

Во-первых, владельцу сайта и его сотрудникам

Чтобы знать, как добавить новый пост в блог, управлять заказами в интернет-магазине, регистрировать новых пользователей и т.д.
Чтобы не тратить свое время на обучение новых сотрудников и не зависеть от старых.

Если ваш сайт реализован на CMS (Системе Управления Контентом) и содержит исключительно "коробочный" функционал без каких-либо изменений, то документация к нему уже скорее всего готова, вот пример для CMS NetCat. Однако, в реальности для сколько-нибудь сложных и живых проектов всегда возникает новый, нестандартный функционал. Если взаимодействие с ним не очевидно, значит он должен быть описан подобным же образом.

Во-вторых, владельцу и программистам сайта

Чтобы знать, не только как запрограммирован сайт, но и почему именно так.

Как ни странно, именно вопрос "Почему?" самый каверзный, что объясняется следующими особенностями долгосрочной веб-разработки:

  • Итерационный подход. В большинстве случаев развитие сайта или веб-сервиса - это постепенный поэтапный процесс. Сначала делается одна часть функционала. Потом другая. Потом подтягивается первая. Потом добавляется третья. И все они как-то связаны друг с другом. Редко когда веб-сервис делается сразу от начала и до конца, потому что Интернет развивается довольно динамично и чтобы соответствовать времени, сайты должны постоянно развиваться.
  • Непредсказуемость. Никогда заранее неизвестно, как предстоит развивать сайт в будущем и как именно будут связаны друг с другом новые и старые функционалы.
  • Забывание. Все забывают всё. В большинстве случаев все подробные детали разработки функционала полностью стираются из памяти примерно через 2 месяца. Не только из памяти программистов, но и владельца сайта. Поэтому, если через 4 месяца возникнет необходимость подключить новый модуль, ответ на простой вопрос "возможно ли это и сколько будет стоить" может превратиться в боль.

Итак, из-за этих особенностей в долгосрочной перспективе любой активно развивающийся веб-проект стремится погрузиться в хаос.

Документация создается для уменьшения хаоса

Больше всего это напоминает проектирование городского пространства и дорожной сети в нем (см. SimCity). Представьте, что вы Главный Архитектор и отвечаете за планировку деревни, стремящейся перерасти в город. Если пустить все на самотек и решать сиюминутные задачи, то на первых порах деревня будет развиваться очень динамично, но в среднесрочной перспективе возникнут проблемы. Дороги начнут упираться в дома. На нужных перекрестках не будет хватать места для развязок. Варшавское и Каширское шоссе десятилетиями будут разделены промзоной до самого МКАДа. Дальнейшее развитие будет становиться все более и более сложным и дорогим.

Ответственный Главный Архитектор начнет с того, что продумает:

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

Продумав, он все это это запишет и получится Документация на Город.

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

Как мы документируем проекты?

При создании документации для конечных пользователей сайта, работает правило:

Хороша та документация, которой нет

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

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

Хороша та документация, которая удобна и в восприятии, и в расширении

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

Для архитектурно не сложных и четко очерченных задачах мы иногда ограничиваемся разработкой прототипа интерфейса с комментариями, например с помощью https://moqups.com/ Посмотрите примеры в нашем портфолио, скриншоты из ТЗ внизу страниц:

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

Несколько примеров:

При документировании каждой сущности мы стремимся:

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

Вся информация сохраняется в едином месте. Один проект - один вики-сайт. Любое изменение проекта - это сначала update документации, а только потом внедрение. Никаких мучительных поисков ответов в почте/месседжерах/телефонах. Процесс техподдержки и развития проекта становится комфортным как для разработчика, так и для заказчика, экономит время и силы.

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

Блог

Наши конкурентные преимущества

Состоят в нескольких уникальных подходах к работе, которые вы не встретите у большинства конкурентов.

далее

Как и зачем мы документируем проекты

Стиральная машина - источник вечных страданий и неразрешимых вопросов. Какую кнопку нажать? А если светлое вместе с темным, то это ничего? Зачем здесь столько отделений и почему рядом стоит столько коробочек и бутылочек? Что сделать, чтобы моя единственная и любимая футболка не села на 5 размеров, как в прошлый раз?

далее

Требовательно, нудно, и поэтому результативно

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

далее

Весь блог тут