Прежде чем приступить к разработке документации как таковой, необходимо наметить и спланировать общую логику изложения. Может показаться, что жанр технической документации крайне прост: ведь его задачей является "всего лишь" сообщение пользователю некоторых сведений о продукте. Однако если Вы будете исходить из этого в своей работе, Вы будете создавать образцы документации, вовсе непригодные или едва пригодные для практического использования, - даже если все необходимые сведения будут там содержаться. Пользователь - это человек, который стоит перед лицом новой, незнакомой ему реальности - программного продукта и хочет не просто узнать об этой реальности побольше, а понять, как к ней подступиться, и главное, как с ней работать. Логика Вашего изложения призвана ему в этом помочь; поэтому она должна отправляться от знакомых ему вещей и помогать ему шаг за шагом осваивать вещи новые.

Поль Дирак начал одну из своих лекций так: "Поскольку никто не знает, что такое электрон, мы будем изучать, как он движется".

Мы бы описали ситуацию в следующих выражениях. Область повседневной деятельности пользователя (внешняя область) (см. Примечание 1) и область функционирования программного продукта разделены. Первая из них пользователю кажется близкой и понятной, а ее задачи - насущными (см. Примечание 2). Вторая же, напротив, является, как правило, чуждой, непонятной, и по большому счету, неинтересной для пользователя. Можно сравнить эти две области с горными долинами, лежащими по разные стороны от горной цепи.

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

Однако Вы описываете этот способ не сразу, а в несколько этапов. Внешняя область разбивается на типичные задачи, этим задачам, в свою очередь, ставятся в соответствие действия, осуществляемые непосредственно программным продуктом с его внутренними объектами (см. Примечание 3): файлами, папками и т. д. А уже эти действия, в свою очередь, осуществляются посредством конкретных процедур, выполняемых пользователем в интерфейсе программного продукта. Таким образом, в описании продукта Вы проходите через несколько промежуточных уровней; каждый следующий уровень конкретизирует, более детально разъясняет предыдущий (см. Примечание 4):

1. Внешняя область: называется и кратко, по минимуму, описывается внешняя область, которую призван обслуживать программный продукт
2. Типичные внешние задачи: перечисляются наиболее актуальные для пользователя внешние задачи, которые могут решаться с использованием программного продукта. Кратко описываются основные объекты внешней области, а также те действия, которые могут производиться с этими объектами и которые позволяют решить те или иные внешние задачи.
3. Соответствие между внешними и внутренними объектами: устанавливается соответствие между внешними объектами и объектами, которыми оперирует программный продукт; например, между документами, чертежами, слайдами, с одной стороны, и файлами того или иного формата - с другой. Определяется, какие действия с внутренними объектами необходимо выполнить, чтобы решить те или иные актуальные для пользователя внешние задачи
4. Конкретные процедуры: даются исчерпывающие инструкции по выполнению конкретных процедур.

Например, программный комплекс бухгалтерского учета позволяет выполнять широкий круг задач по ведению бухгалтерской отчетности. Пусть нам необходимо обновить и пополнить бухгалтерскую отчетность в фирме. ? Для этого: необходимо составить новый отчет. Для этого: необходимо создать новый файл в программном комплексе бухгалтерского отчета и ввести необходимые данные. Для этого: необходимо выбрать в меню "Файл" пункт "Создать" и т. д.

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

Например, пусть Вы описываете поисковую систему, которая допускает поиск по сложному условию, которое задается комбинацией логических функций И, ИЛИ, ИСКЛЮЧАЯ от более простых условиях, задаваемых значениями полей поиска. Однако не всякий пользователь имеет представление о логических функциях и их свойствах; поэтому имеет смысл рассказать об этом особо. Прилагаемые к описанию процедуры пояснения не имеют отношения к остальному изложению, а лишь делают описание процедуры более доступным и годным для использования в работе любым, даже не слишком подготовленным пользователем.

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

Логика описания продукта должна основываться на двух базовых принципах:

• От поставленной цели - к способу ее достижения.
• От более общего уровня описания - к более частному и детализованному.

При этом, вообще говоря, не допускается:

• Ставить цель и не указывать способ ее достижения.
• Указывать способ достижения цели, не сформулировав самой цели.
• Пропускать тот или иной уровень описания.

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

С другой стороны, очень важно последовательно разграничивать уровни описания продукта, не допускать их смешения. Тогда пользователь сможет шаг за шагом пройти "маршрут", который Вы для него наметили, и по ходу дела осваивать работу с продуктом.

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

Говорят, когда-то давно трех строителей, работавших плечом к плечу, спросили: "Что вы делаете?" Один ответил: "Кладу кирпичи". Другой: "Возвожу кирпичную стену". Наконец, третий сказал: "Я строю Шартрский собор". Каждый был по-своему прав. Но Вы действуете в одиночку, и Вам придется работать за троих.

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

Начните с того, что задайте сами себе ряд вопросов из тех, которые потенциальный пользователь мог бы задать Вам, например:

• Зачем мне этот продукт?
• Почему мне не обойтись без программного обеспечения?
• Почему мне не обойтись именно без данного программного продукта.
• Какие конкретно "внешние" задачи помогает решить программный продукт?
• Какие трудности - ранее непреодолимые - он позволяет преодолеть?

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

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

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

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

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

Примечания

1. Иногда ее называют предметной областью - когда, например, речь идет о прикладной программе для какой-либо специализированной сферы (финансовая и бухгалтерская отчетность, САПР и т. д.). Однако такой термин мог бы спровоцировать неправомерное сужение смысла. Ведь областью деятельности, для которой пользователю понадобился программный продукт, может быть какая-то универсальная практика, вроде редактирования текстов или планирования рабочего времени, игры и развлечения, или наконец, обслуживание компьютерных систем и программного обеспечения. Мы называем эту область внешней (по отношению к программному продукту), а принадлежащие к ней объекты и задачи - внешними объектами и задачами.
2. Иногда программный продукт не просто помогает решить какие-то повседневные задачи, с которыми пользователь уже не раз сталкивался, а сам формирует специфическую область деятельности (например, программные комплексы для работы в Internet; см.  п. 1.2). В этом случае необходимо вначале описать эту область, поставить перед пользователем характерные для нее задачи, объяснить ему, почему они для него важны, - одним словом, осмыслить ее как внешнюю область, а уж затем показать, как ее задачи решаются с помощью данного программного продукта.
3. Внутренними объектами мы называем объекты, с которыми работает непосредственно программный продукт. Например при описании работы с Microsoft Word следует выражаться примерно следующим образом: 'Внешнему объекту "Договор об аренде ?666" соответствует внутренний объект - файл dog_ar666.doc'. Мы говорим также о внутренних задачах, действиях и т. д.
4. Разумеется, приведенная ниже последовательность является достаточно условным обобщением, поскольку каждый конкретный случай имеет свою специфику. Мы ставили своей задачей охарактеризовать общую логику, не вдаваясь в частности.