Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому

Рассказывает Дмитрий Толоконников, бизнес-аналитик департамента ИТ-аутсорсинга ALP Group

Больше пяти лет я занимаюсь бизнес-процессами. В особенности процессами технической поддержки, которую мы оказываем коммерческим и государственным компаниям. Например, я слежу, чтобы уровень качества IT-обслуживания соответствовал международным стандартам. Я программирую и работаю с документацией — пишу регламенты и процедуры, описываю процессы, выпускаю инструкции.

Всё это время я неосознанно «перетаскиваю» общие принципы программирования в работу с документами. Это помогает мне не делать бесполезные «спагетти-простыни» и писать внятные рабочие документы с ясной структурой, даже если документация очень объёмная и должна часто меняться в соответствии с изменениями в компании и все её части должны быть связаны воедино, чётко объяснять, как что-то работает. Возможно, мои приёмы помогут и вам.

Принципы работы с текстом

DRY — Don’t repeat yourself. Не повторяйся

Если вы вставили один и тот же блок в 10 разных регламентов и что-то меняете в нём, то у вас образуется 10 одинаковых мест, куда нужно внести одинаковые изменения. Вероятность забыть об этом тоже растёт, даже если вы пользуетесь бессмертным «Ctrl+C» — «Ctrl+V». Особенно в последней паре документов.

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

KISS — Keep it simple, stupid. Не усложняй

Посмотрите вокруг: люди привыкли к простоте. Интуитивно понятные интерфейсы и всплывающие подсказки в приложениях. Принцип одного окна в IT-обслуживании. Засилье коротких статей и обучающих видео в Интернете. Той же простоты они ждут и от рабочих документов.

Этот принцип я обычно использую как маркер. Если описание процесса слишком сложное — нужно упростить процесс. Если инструкция к приложению слишком замысловатая — надо доработать приложение.

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

YAGNI — You ain’t gonna need it. Тебе это не понадобится

Это продолжение принципа KISS. Обычно я применяю его, когда собираюсь создать универсальное решение с заделом на будущее. Проблема в том, что такое решение — само по себе усложнение. Не факт, что в будущем оно понадобится. Обычно нет смысла создавать всеобъемлющее описание бизнес-процессов направления, которое только сформировалось и активно развивается. Практика показывает, что будущее внесёт серьёзные коррективы.

Но здесь важно разумно подходить к вопросу. Есть вещи, изменение которых дорого обходится. Их как раз нужно готовить с заделом на будущее. В программировании эту работу относят к архитектуре приложения, а в документации просто сразу говорят: «Это нам не понадобится». И в будущем с трудом навёрстывают упущенное.

Принципы работы со структурой

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

SRP — Single Responsibility Principle. Принцип единственной ответственности

Яркий маркер нарушения принципа — наличие побочных действий. Например, метод класса отвечает за отправку клиенту уведомления о новом заказе в интернет-магазине, но при этом ещё и обновляет текущий баланс клиента.

То же самое справедливо и для документации. Например, в регламент регистрации обращения клиента не нужно впихивать что-то «заодно»: принципы вежливого общения с клиентами, краткое описание self-service портала и т. д.

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

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

SLAP — Single Level of Abstraction Principle. Принцип единого уровня абстракции

Является логичным продолжением принципа единственной ответственности (SRP).

Применение принципов KISS и SRP побуждает писать небольшие, простые и понятные документы. Но эти документы нужно собрать в такую же простую и понятную структуру. Здесь помогает выделение и соблюдение уровней абстракций.

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

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

LoD — Law of Demeter (Don’t talk to strangers). Закон Деметры (Не разговаривай с незнакомцами)

Если применить закон к документации, то каждый документ:

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

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

Итого

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