Dimdim SoftWare
Мастерская Dr.dimdim
ГлавнаяПоискНаписать письмо
ГлавнаяМоделированиеПроектированиеТЗРазработкаИнтерфейсСтатьиСсылкиАвтор
Главная > Справка

Глава из книги «Shareware: профессиональная разработка и продвижение программ». Станислав Жарков

Как писать документацию

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

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

Для решения первой задачи, т. е. помощи пользователям в преодолении различных проблем с освоением и работой с программой, следует включить, в документацию раздел Introduction (Введение), в котором рассказать о назначении программы, а также гораздо более объемный раздел Description (Описание), в котором дать описание меню, диалоговых окон и прочих эле­ментов программы.

Считается, что для составления текста справочных систем применяются два подхода: либо вы рассказываете для чего что-то предназначено, либо о том, как что-то сделать (wanting to know vs. wanting to do). Однако, на мои взгляд, при определении структуры и содержания Справки эти два подхода нужно объединить и добавить в документацию раздел How to... (Как сделать...). Де­ло в том, что все вопросы, с которыми пользователи обращаются к справоч­ной системе, можно разделить на две группы: "Что означает этот элемент (меню, кнопка, флажок и т. п.)?" и "Как мне сделать то-то (отфильтровать данные, переформатировать текст, настроить параметры и т. п.)". Если же в документации будет только описание элементов программы, то на вопросы категории "Как мне сделать то-то?" найти ответ для не очень опытных поль­зователей будет гораздо сложнее.

Кроме того, нужно создать в Справке раздел Technical Support (Техническая поддержка), где указать адреса e-mail, по которым пользователи могут задать свои вопросы, а также привести ссылки на источники дополнительной ин­формации о программе, если они имеются: форум на Web-сайте, список ответов на часто задаваемые вопросы (FAQ) и т. п.

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

Если у вас имеется несколько продуктов, то удачным шагом будет создание еще одного раздела: Оur products (Наши продукты), где будет дана информация о ваших других программах и ссылки на их Web-страницы и файлы для загрузки. Эта информация будет полезна для тех пользователей, которые получили дистрибутив программы не с Web-сайта разработчика (а, например, скачали его с сервера интернет-архива или купили в составе сборника программ на CD-ROM) и ничего не знают о других про­дуктах этого же автора. Очень часто бывает, что люди начинают интересо­ваться ими, скачивают, тестируют и — оплачивают регистрацию.

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

Для российских программистов, составляющих справочную систему, большая проблема — английский язык. Одно дело меню и небольшие информа­ционные сообщения в интерфейсе программы, здесь больших сложностей нет (хотя в некоторых российских программах даже в меню и диалоговых окнах встречаются ошибки). Но вот документация... Здесь требуется более глубокое знание языка. Грамматические и орфографические ошибки очень сильно портят впечатление обо всем продукте, и это приводит не только к отрицательным обзорам в журналах и на Web-сайтах, но и существенно снижает объем продаж. Качественный английский язык документации — одно из самых главных требований к серьезному продукту.

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

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

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

Один из российских разработчиков рассказывал такую историю. Некий иностранный программист, продававший конкурирующую програм­му (утилита для общения в локальной сети), украл у него полностью всю документацию, включив ее в дистрибутив своего продукта. Однако он забыл исправить адреса, на которые указывали ссылки в Справке: текст на них был изменен, но вели они по-прежнему на оригинальный Web-сайт. По­страдавший от плагиата смотрел на это сквозь пальцы, т. к. его программа продавалась очень хорошо, и мелкий конкурент его не особенно волновал. Но однажды он получил письмо от пользователя, который интересовался, почему ссылка из документации программы, которую он недавно приобрел, ведет на совсем другой сайт, где продается вроде бы похожий продукт. "Это что, новая версия?" — спрашивал удивленный пользователь. Наш соотечест­венник объяснил ему ситуацию и предложил этому человеку, т. к. он уже купил программу плагиатора, скидку (в 20%) при переходе на свой продукт. Пользователь согласился: воров никто не уважает.

Контекстная справка

Пользователи обычно не любят запускать справочную систему из меню Help (Справка), т. к. в этом случае приходится самостоятельно искать нужный раздел Справки.

Зато они вполне готовы нажать клавишу <F1> u каком-либо диалоговом окне или воспользоваться кнопкой с вопросом ("What's This?" -Что это такое?'), чтобы получить пояснение именно по текущей ситуации.

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

Конечно, не нужно предлагать помощь также навязчиво, как известная скрепка-помощник из Microsoft Office. Созданный  для придания "ящику" большей интеллектуальности и, так сказать, человечности. Помощ­ник заслужил неоднозначные отзывы. У некоторых пользователей, которые не смогли понять, как отключить Помощника, скачущая по экрану скрепка даже вызывала истерику.

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

Так как при появлении на экране диалога у пользователя чаще всего появ­ляется вопрос "Почему?", то вполне стандартным приемом является допол­нение текста диалога подсказкой: "For help, press F1" (Для справки, нажмите F1). Использование такого предложения помощи полезно не только в диалогах, но и в обычных окнах, где оно выводится в строку со­стояния сразу после старта программы. И даже если пользователю в на­стоящий момент справка не нужна, такое ненавязчивое предложение помо­щи как бы сигнализирует, что программа, в случае необходимости, может дать пояснения.

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

С контекстной справкой связан интересный случай, который еще раз на­помнил не только составителям документации, но и проектировщикам ин­терфейсов о том, что с пользователями нужно обращаться максимально вежливо и учтиво. Как рассказал один из посетителей Web-сайта iarchitect.com, однажды справочная система инженерного пакета AutoCAD Mechanical от фирмы Autodesk показала вот такое сообщение "Нажми здесь, идиот". Кому-то это сообщение — "Нажми здесь, идиот" — может показаться смеш­ным, но на самом деле оно выражает скорее пренебрежительное отношение к пользователю. Как оказалось, человек, ответственный за этот участок программы, пошутил, полагая, что это сообщение не увидит ни один поль­зователь. Но его работодатель, компания Autodesk, не оценила его чувство юмора: служащий был уволен, а тысячам заказчиков компании были разо­сланы письма с извинениями.

Вверх

<<Назад

Главная| ИС.. | Моделирование | Проектирование |ТД | Разработка | Интерфейс | Статьи | Ссылки | Автор
DimDim SoftWare Мастерская Dr. dimdim Copyright 2003-2004
Администратор info-system@mail.ru
Последнее обновление 26-Дек-2003