Правила ведения и составления документации.

Введение.

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

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

Построение фраз и предложений.

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

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

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

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

Использование примеров.

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

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

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

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

Историческая ценность.

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

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

Поэтому при критических изменениях желательно сохранить устаревшую часть документации в виде сноски к найденному несоответствию или противоречию относительно текущего состояния документа. Неплохим инструментом для этого может служить контроль ревизий, и не только он.

Достаточность изложения.

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

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

Ясность изложения.

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

Разбиение на секции.

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

Стиль изложения.

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

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