Глава 10: Тестирование документации 255

касается и публикации: автор сам проверяет, все ли страницы на месте, не распечатаны ли они вверх ногами и т.п. Подробнейшее обсуждение процес­са разработки и редактирования документации можно найти у таких авто­ров, как Брокман (Brockmann, 1990), Хастингс и Кинг (Hastings and King, 1986) и Прайс (Price, 1984).

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

Первый черновик

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

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

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

256 Часть II: Приемы и технологии тестирования

Второй черновик

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

• Проанализируйте структуру документа и как можно раньше со­ставьте свои комментарии. Если вам не нравится порядок глав, если вы думаете, что материал нескольких из них лучше объединить в одну главу или, наоборот, разбить одну главу на несколько, скажи­те об этом пораньше. С предложениями о перестановке глав можно немного подождать, но слишком затягивать тоже не стоит. Чем даль­ше, тем труднее будет автору менять структуру книги.

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

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

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