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

Ещё в 2009 г. опытный технический писатель Боб Реселман написал статью, в которой изложил семь правил написания документации. Они актуальны до сих пор, свидетельство чему — приглашение автора на очередную конференцию Linux Expo, которая состоится в конце января в Калифорнии.

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

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

1. Избегайте сухости

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

Боб Реселман утверждает, что если автор пишет текст, получая удовольствие от процесса, то и читаться он будет аналогично. Если же автору скучно, то скучно будет и читателю.

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

2. Читатель должен понимать, что делать после прочтения

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

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

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

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

3. Начинать следует со структуры

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

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

При составлении схемы документа следует руководствоваться двумя простыми правилами:

· любой раздел должен иметь как минимум два равных подраздела;

· в любом разделе должно быть по крайней мере два предложения.

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

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

Иными словами, отсутствие структуры и чрезмерная структуризация — это одинаково плохо. И то, и другое затрудняет восприятие материала.

4. Избегайте двусмысленных местоимений

Сам Боб Реселман считает этот пункт смешным, но важным. Особенность технического текста заключается в том, что читатель должен точно понимать, что написал автор. И ему следует это учитывать.

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

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

5. Ясность = иллюстрация + слова

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

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

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

6. Понятие — логическая иллюстрация — пример

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

Допустим, автору следует описать алгебраический транзитивный закон «если A равно B и B равно C, то A равно C». При применении шестого правила это будет выглядеть так.

Сначала описывается само понятие: если А = В и В = С, то А = С.

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

Наконец, читателю предлагаются конкретные примеры. Если 7 = 3 + 4 и 3 + 4 = 5 + 2, то 7 = 5 + 2. Если х + у = г и г = 2а, то х + у = 2а. И т. д.

Такая форма подачи материала удобна читателю, к тому же она понятна людям с различными типами мышления. Кому-то проще даются общие вещи, кому-то — конкретные примеры. А кто-то посмотрит на иллюстрацию и ему всё станет ясно.

7. Редактируйте

Даже опытный технический писатель Боб Реселман признаётся, что с первого раза у него ничего не получается. Написание документации требует значительных усилий.

Первая версия всего-навсего даёт ему представление о том, что он действительно хотел написать. Вторая приносит ясность. И только третью можно адресовать читателям.

Отсюда важное следствие. Хорошую документацию нельзя написать «между делом». Поэтому руководителю проекта следует тщательно всё взвесить. Может быть, выгоднее будет пригласить технического писателя, а не отвлекать программиста на пару месяцев от основной работы? Даже если это слишком накладно.