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

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

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

Технический евангелист проекта Cycle Computing Бен Коттон решил поделиться своим опытом с начинающими техническими писателями. На сайте OpenSource.com он излагает основные правила, которыми следует руководствоваться при редактировании документации. Несмотря на то, что его советы адресованы англоязычной аудитории, большинство из них достаточно универсальны и ими могут пользоваться отечественные авторы.

Используйте «активные» утверждения

В отличие от литературного произведения, техническая документация не должна допускать различных толкований. Для этого эксперт советует всегда использовать «активные» утверждения, предпочитая их «пассивным».

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

Если применить его к этим фразам, то получится следующее:

  • если вы нажмёте на кнопку «да», то вы удалите свои данные зомби;
  • если нажать на кнопку «да», то данные будут удалены зомби.

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

Исключайте жаргон

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

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

Избегайте распространённых ошибок

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

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

Удаляйте потенциальные двусмысленности

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

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

Следуйте руководству по стилю

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

Заменяйте ничего не значащие слова

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

Он считает, что лучше оперировать конкретными категориями. После редактировании фраза должна была стать примерно такой: «следование этим советам позволит увеличить количество пользователей продукта на 40%».

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

Не используйте слово «просто»

Употребление этого слова в инструкциях категорически недопустимо. В конце концов, если всё так просто, то зачем вообще нужна какая-то инструкция? Пользователь и так разберётся на какую кнопку ему нужно нажать.

Увы, порой начинающие авторы путают жанры. Документация — это не рекламный ролик кухонного гаджета.

Будьте осторожны с местоимениями

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

Коттон советует не использовать местоимения «я» и «мы». Разве что в самом крайнем случае, когда совершенно очевидно, что они не могут никого запутать.

Главное — чтобы было понятно

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