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

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

Поэтому первое, что я сделал в своих функциональных спецификациях, — избавился от 10% объёма, просто отказавшись от вводных слов типа:

— В этом разделе находятся следующие элементы
— Меню навигации состоит из
— Карточка товара включает в себя следующие составляющие
— Ссылка ведёт в раздел такой-то

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

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

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

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

Третье — описываю логику поведения и значения по умолчанию для отдельных сущностей, а в описании конкретной страницы уточняю только те, которые будут специфичны для неё. Взять, например, любую форму для отправки данных. В начале документа у меня есть полторы страницы текста «Общие принципы работы форм», где рассказано обо всех мелких нюансах: в каком поле курсор по умолчанию, где отображаются сообщения об ошибках, как происходит валидация, как блокируется кнопка отправки после нажатия (чтобы предотвратить случайное повторное нажатие) и так далее.

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

Таким же образом я описываю общие принципы работы ссылок, языковых версий интерфейса, «печенек», модальных окон и прочих сквозных элементов.

Суммарно эти оптимизации привели к тому, что мои функциональные спецификации заметно «похудели», при этом не теряя полноты описания. Вместе с ними без следа исчез и подход «Чем толще техническая документация — тем лучше». ФС должна быть ровно такой толщины, которая позволяет минимальным количеством текста максимально описать систему.

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