Стиль
1. Пишите так, чтобы уровень удобочитаемости документа соответствовал категории его предполагаемых пользователей. Чтобы определить средний уровень удобочитаемости текста, используйте формулу Ганинга:
А. Случайным образом выберите из документа фрагмент длиной в 100 слов.
Б. Сосчитайте число предложений и поделите на 100, чтобы получить среднюю длину предложения.
В. Сосчитайте во фрагменте число слов с тремя и более слогами.
Г. Добавьте это число к средней длине предложения.
Д. Умножьте сумму на 0,4. Полученное число и будет представлять собой оценку уровня удобочитаемости документа.
Е. В случае если найденная оценка окажется больше восьми, повторно отредактируйте документ, чтобы оценка стала ниже этого предела [1].
2. Представляйте действия в логической последовательности и описывайте их шаги в том порядке, в котором они должны осуществляться.
Примеры.
Неправильно: «До ответов на вопросы прочтите инструкции».
Правильно: «Ознакомьтесь с инструкциями перед ответами на вопросы».
3. Избегайте применения предложений в отрицательной форме.
Примеры.
Неправильно: «Не печатайте в графе 7».
Правильно: «Оставьте графу 7 пустой».
4. Используйте активные, а не пассивные конструкции. Примеры.
Неправильно: «Ваша фамилия должна быть введена в строке 5».
Правильно: «Введите свою фамилию в строке 5».
5. Используйте простые грамматические конструкции.
6. Используйте короткие абзацы, содержащие по одной мысли.
7. Помещайте основную мысль предложения в его начале.
8. Чтобы провести пользователя через сложное задание, используйте древовидную структуру описания, например: «Если ответ на вопрос 6 «да», то смотрите раздел 3, если «нет» — раздел 4».
9. Располагайте материал от простого к сложному или от Общего к частному.
10. Экономно используйте жаргонные и технические термины. Определяйте каждый термин, как только он появляется, и давайте (если необходимо) в скобках его сокращение. Ссылайтесь на определение, если вы используете термин в последующих разделах.
11. Используйте термины, которые будут понятны пользователю. Давайте полное, явное определение, чтобы четко объяснить его подразумеваемое значение, особенно если термин используется в контексте, отличном от привычного.
12. Термин должен иметь только одно значение и использоваться по всему тексту только в этом значении.
13. Используйте везде одни и те же аббревиатуры. Убедитесь в том, что они действительно вами определены. Обязательно сделайте их отличающимися от других используемых сокращений.
14. Сокращайте термины только тогда, когда аббревиатура значительно короче или более осмысленна, чем исходный термин.
15. Тщательно определяйте вводимую сложную символику; например, для команды типа COPYfile-1 file-2 объясните, что file-1 и file-2 — это имена файлов, подставляемые пользователем. Дополняйте текстовые описания конкретными примерами, например: «COPY SALARY-83, SALARY-ARCHIVE».
16. Используйте систему отсчета, понятную пользователю; например, 12-часовой отсчет времени удобен для гражданских применений, а 24-часовой — для военных {12].
Учебные материалы
Значительная часть документации используется в качестве учебного материала. В связи с этим К - Адаме и И. Халац в методике, выпущенной ими в 1983 г.1', дают практические советы по созданию документации, которая помогает в процессе самообучения. Приводимые ниже рекомендации заимствованы у названных авторов с их любезного разрешения:
Во-первых, привлеките внимание пользователей. Заинтересуйте их, чтобы у них возникло желание знать больше.
Во-вторых, сообщайте пользователям о том, что они будут изучать. Резюмируйте наиболее важные аспекты в соответствии с целями обучения.
В-третьих, стимулируйте возвращение к пройденному материалу. Помогайте пользователям программного обес -
■> Adams К. A., Halasz I. М., 25 Ways to Improve Your Software User Manuals, 1983.
Печения сопоставлять то, что они собираются изучить, с тем, что они уже знают.
В-четвертых, разъясните пользователю основную суть изучаемого материала, основополагающие правила и принципы.
В-пятых, направляйте процесс обучения в нужную сторону с помощью подсказок, наводящих сообщений, советов и примеров. Чем больше времени затрачивается на решение некоторой задачи, тем выше уровень достижений. В-шестых, предлагайте пользователю действовать. Давайте ему возможность решать реальные задачи, поскольку люди обучаются работая.
В-седьмых, обеспечивайте обратную связь. Успех пользователя — это наиболее сильный стимул к продолжению обучения.
В-восьмых, усиливайте запоминание, сохранение и передачу приобретенных пользователем знаний. Для этого предлагайте ему разнообразные примеры и применения. Привязывайте изученные принципы к более реальным проблемам.
В-девятых, подытоживайте самое главное из того, что было изучено. Повторение пройденного облегчает обучение.
В-десятых, оценивайте общее качество работы обучаемого лица. Если установлена обратная связь с пользователем, предоставьте ему возможность продемонстрировать все усвоенные знания.
