Конечно, подобный подход позволяет снижать затраты на выпуск документации, но вместе с тем сказывается на эксплуатационной эффективности программного продукта.
Компания «Философт» наряду с выполнением проектов по созданию технической документации долгое время проводила исследовательскую работу по тому, какой надлежит быть документации на программный продукт. Соответствующий опыт вылился в книгу Ю.В. Кагарлицкого «Разработка документации пользователя программного продукта», посвященную проблемам методики ее подготовки и стилю изложения. Интерес к данной работе вызван тем, что если вопросы состава и содержания такой документации рассматриваются во многих публикациях и существуют даже соответствующие стандарты, то методика ее подготовки и стиль изложения всегда оставались на уровне устных преданий.
Как отмечает Ю.В. Кагарлицкий, его книга не находится в противоречии с известными документами ЕСПД и ГОСТ РИСО/МЭК 12119-2000, а главным образом посвящена тем проблемам, с которыми технический писатель сталкивается при создании качественной документации, в ней также предложены рекомендации по разрешению этих проблем.
Первые две главы книги «Постановка задачи» и «Требования к содержанию документации» базируются на представлении о жизненном цикле программы и соответствуют обычному подходу технических писателей к организации работы над пользовательской документацией. Они содержат ответы на вопросы: кто работает над документом, каков предмет документа с точки зрения программного продукта и его пользователя, а также каковы требования к содержанию документа. Почти две трети книги посвящены собственно методике и стилю написания документации.
В третьей главе рассматриваются вопросы структуры документации и отмечается, что структурированность документа не только обязательна, но и должна охватывать его целиком. При обсуждении проблемы деления документа на основные структурные элементы автор книги касается не только формальной стороны, но и предлагает стилевые разрешения парадокса уровня формализации структуры. Помимо этого автор рассматривает проблему структуры сплошного текста и ее стилевого деления, а также представление типов информации и их взаимного расположения. Подвергнуты анализу проблемы логического повтора в тексте, перекрестных ссылок и случаи их использования.
Четвертая глава книги рассматривает основные элементы текста документа, слова и формулировки, оказывающие значительное влияние на качество пользовательского документа, так как передают его основную смысловую нагрузку. Поэтому в разделах этой главы рассматриваются вопросы, связанные с использованием терминологии, в которой Ю.В. Кагарлицкий выделяет понятия, используемые для описания работы с любым программным продуктом, например обозначение элементов пользовательского интерфейса и описание работы с ним. Интересны авторские стилевые комментарии по поводу ограничения использования слов-«артиклей» в тексте пользовательского документа.
В этой же главе автор обращает внимание на смысловые и стилевые требования к формулировкам, включающие строгость и однозначность, а также лаконичность и завершенность.
Весьма существенным, по мнению автора, является и порядок изложения сведений. К стилевым особенностям создания документа отнесены проблемы рассмотрения взаимосвязанных понятий, а также выбор канонического порядка изложения сведений или унификации порядка изложения. Также в книге описана специфика представления в программной документации сведений о работе с реальными и виртуальными объектами и событиями. И наконец, Ю.В. Кагарлицкий на последних страницах книги обсуждает вопрос — писать документацию следует строго или образно?
Книга написана с учетом значительного опыта автора в сфере технического писательства и, следовательно, для многих читателей послужит хорошим источником знаний. Вместе с тем стоит обратить внимание на то, что принятая в книге концепция пользовательского документа базируется на жизненном цикле программы и не учитывает его судьбу в условиях эксплуатации, например внесения изменений по ее результатам и по устранению недочетов.
