Про документы

Назначение документирования

Есть две основных задачи документирования:

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

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

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

Как устроен документ

У документа есть 3 основных части — это начало, середина и конец:

Начало

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

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

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

Введение — это обзор документа о том, в котором читатель может быстро получить представление о том, что в этом документе есть и где что искать. По сравнению с оглавлением, это более подробное описание документа, описывающее самое интересное и важное из каждого раздела.

Середина

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

Заключение

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

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

Приложения

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

Свойства хорошего документа

Что такое хороший документ, чем он отличается от плохого?

Порядок изложения

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

О структуре

Желательно, чтобы уровней в документе было не больше 2-х, для того чтобы человек мог ориентироваться в навигации по документу. Рекомендуемое число разделов — не больше 7-ми на каждый из уровней. Понятно, что разделов может быть и 10-15, но лучше попытаться ограничиться разумным числом — 7, 5, 9.

Объём

В целом, чем более компактный документ, тем он легче читается, поэтому полезно, чтоб документ не превышал по объему 10-15 страниц.

В случае требований это не всегда применимо, т.к. в требованиях формата ТЗ мы фиксируем ключевые функции системы, описываем её характеристики и это может занимать 15-20 страниц.

Бывают спецификации требований, которые представляют собой часть проектирования (элементы эскизного проекта и технического проекта в терминах ГОСТ 34), в которых описаны детально сценарии взаимодействия. Такие документы не могут быть ограничены 15 стр., они должны быть объёмными.

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

Нумерация абзацев

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

Нумерация в духе «пункт 2.7» позволяет легко сослаться на него в письме. Конечно, есть некоторый риск ошибки, но тем не менее. В письме, в мессенджере и по телефону человек достаточно легко может найти этот пункт, понять и обсудить его,  что-то с ним сделать. В противном случае, если нумерации нет, то приходиться делать цитату, либо говорить что-то вроде «3-й абзац из такого-то раздела».

Формулировки высказываний

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

Пояснения и комментарии

С одной стороны, документ спецификации сам по себе предполагает перечисление формальных утверждений — «система должна X», «система должна Y». Но я рекомендую перед каждым разделом или блоком делать текстовое описание откуда взялась информация, какая была логика принятия решений, какие в этом пункте есть подводные камни. Если потом Публикатор или Заказчик захочет получить формальную спецификацию, например, для тендера, то эти пометки и комментарии потом можно удалить. Но помните, что эти комментарии здорово помогают читателю понимать и читать текст как изложение истории, а не как формальную сухую спецификацию.