Кто пишет инструкции для пользователей

Как мы в «Активе» пишем пользовательскую документацию. Почему это важно

Что пользователь хочет видеть в пользовательской документации? Что его в ней раздражает? Эти вопросы задаёт себе каждый, кто пишет такую документацию, но далеко не каждый правильно отвечает на них. Совсем небольшой процент пользователей читает документацию. Давайте разберёмся, почему так и как сделать пользовательскую документацию эффективной и изменить отношение пользователей к ней.

Нам мешает негативный опыт

С такой ситуацией сталкивался почти каждый: вам надо быстро освоить какую-то ИТ-систему, она очень сложная, и в ней хранятся важные данные. Метод “проб и ошибок” здесь не подойдёт. Наверняка в такой момент вы вспомнили про руководство пользователя, открыли его и начали внимательно изучать. После 10 минут чтения вы ещё больше запутались, закрыли руководство и начали осваивать систему, используя при этом метод “будь что будет”. И хорошо, если при этом вы не удалили что-то очень важное и не получили результат, о котором будете жалеть, а ведь всякое бывает.

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

Ответ один — хорошая пользовательская документация.

Документация может всё

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

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

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

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

В этой статье я расскажу вам о том, сколько в нашей компании стоит пользовательская документация, и из каких этапов у нас состоит процесс документирования. Let’s go!

Сколько стоит пользовательская документация

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

Рассмотрим на примере инструкции, которую можно написать за 20 часов. Технический писатель за это время напишет 25-страничный документ, в котором будет около 40 скриншотов.

Весь процесс производства инструкции в нашей компании состоит из следующих этапов:

1. Постановка задачи. Её создаёт и описывает менеджер проекта, руководитель проекта или руководитель отдела. На это нужно время, недостаточно просто написать “Опиши процедуру”. Здесь обязательно нужны детали. Например, здесь посчитаем 1 час рабочего времени менеджера проекта. На этапе постановки задачи менеджер проекта назначает консультанта и обозначает круг сотрудников компании, которые могут помочь и объяснят какие-то важные особенности системы. Получается, что цель этого этапа — сформулировать задачу и назначить консультанта

2. Показ системы. Чаще всего здесь задействован системный аналитик, он демонстрирует систему техническому писателю и рассказывает, что и как работает. Прибавим 2 часа работы аналитика + 2 часа технического писателя. Здесь аналитик рассказывает, а технический писатель слушает и задаёт вопросы. Если система сложная, таких встреч может быть несколько. Цель этого этапа — объяснить техническому писателю, как работает система.

3. Написание документа. Здесь главную роль играет технический писатель, но нельзя забывать про вопросы, которые у него могут возникать в процессе написания. Отвечать на них может аналитик, разработчик, менеджер проекта, тот, кто разбирается в продукте и умеет понятно объяснять. Таких вопросов может быть много и хорошо, если технический писатель оперативно получает на них ответы. Прибавим 20 часов работы технического писателя + 1 час работы аналитика + 1 час работы разработчика. Цель этого этапа — создать первую версию инструкции.

4. Рецензирование. Чаще всего читает документ заказчик, в нашем случае — менеджер проекта. На это тоже нужно время, оно зависит от количества страниц в документе и качества описаний. Прибавим 2 часа работы менеджера проекта. На этом этапе он пишет комментарии к документу. Цель этого этапа — проверить документ.

5. Внесение правок. Реализует технический писатель, на этом этапе он тоже может задавать уточняющие вопросы коллегам. Техническому писателю здесь очень важно правильно понять комментарии к инструкции. Прибавим 2 часа работы технического писателя + 1 час работы аналитика. Цель этого этапа — создать вторую версию документа.

6. Тестирование. На этом этапе подключается сотрудник отдела тестирования. Он реализует все описания процедур и оценивает насколько корректно они описаны. Прибавим здесь 2 часа работы тестировщика. Цель этого этапа — проверить корректность описания процедур.

7. Повторное внесение правок. Технический писатель получает от тестировщика комментарии и вносит изменения в инструкцию. Прибавим 1 час работы технического писателя. Цель этого этапа — создание третьей версии документа.

8. Вёрстка документа. Здесь может подключаться дизайнер. Если вёрстка не очень сложная, то технический писатель делает её сам. Прибавим 4 часа работы дизайнера. Цель этого этапа — сверстать документ так, чтобы его было удобно использовать.

9. Публикация документа. Мы публикуем документ на своём сайте на специальной странице. Прибавим 20 минут работы администратора сайта.

Итого:

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

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

100 тысяч рублей или долларов

Вы видите, что технический писатель не один участвует в создании инструкции. Здесь не обязательно называть какие-то точные цифры. Документация стоит денег и ошибки в ней — тоже. Именно поэтому её нужно сразу писать так, чтобы она решала задачи пользователя, приносила ему пользу, а не была чем-то бесполезным и просто “пылилась на полке”.

Сейчас, если в любом поисковике ввести слова “руководство пользователя”, то за 5 минут просмотра результатов вы найдёте как минимум 5 плохих документов и один хороший, а это совсем мало. Получается, что только каждый шестой документ является эффективным, а представьте сколько времени, денег потрачено впустую и надо здесь что-то менять. Давайте делать это вместе, так будет проще обратить внимание всех на эту проблему.

В следующей статье я расскажу про ошибки в документации. Отвечу на вопросы:

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

See you soon!

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

Собственно subj…

А если подробнее… Большие начальники решили пригрузить всех программистов в банке, где я работаю, и заставить их сделать краткое описание каждой программы + инструкцию пользователя. Кто как считает, должен ли программист писать инструкцию к программе, которую он написал, или этим должен заниматься кто-то другой? На западе, напр. этим занимается technical writer. Причем этот человек пишет вообще всю документацию, не только на программы (насколько я знаю).

Re: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Собственно subj…

В целом ты конечно прав. Руководство для пользователей действительно
должны писать профессионалы (технические писатели).
Только вряд ли этот факт поможет тебе в борьбе с начальством.

Кое-какую техническую документацию программеры тоже обычно пишут (спецификации, дизайн)…
Так что я бы поспорил с тем, что технический писатеть
E>пишет вообще всю документацию, не только на программы…

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

В нормальном проекте такие вещи (кто, когда и какие документы пишет)
должны оговариваться на этапе планирования, но это похоже не твой случай.

Re: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Собственно subj…

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

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

… << RSDN@Home 1.0 beta 4 >>

Re[2]: Кто должен писать документацию?

Здравствуйте, bkat, Вы писали:

B>В целом ты конечно прав. Руководство для пользователей действительно
B>должны писать профессионалы (технические писатели).
B>Только вряд ли этот факт поможет тебе в борьбе с начальством.

Я бороться не собираюсь. Сказали писать — буду писать. Просто свою основную работу делать не буду

B>Кое-какую техническую документацию программеры тоже обычно пишут (спецификации, дизайн)…
B>Так что я бы поспорил с тем, что технический писатеть
E>>пишет вообще всю документацию, не только на программы…

Я когда-то (года два назад) говорил с одним американцем, который в то время учился в колледже как раз по специальности technical writer. Ну и в общении с ним сделал такой вывод, что даже в том случае, если в фирме нет программистов, тех. документацию пишут как раз technical writers. И он очень долго не мог понять, что я таких очевидных вещей не понимаю, и что у нас такой специальности вообще нет. Он для этого в колледже 6 лет должен проучиться…

B>Чтобы действительно ответить на твой вопрос, по хорошему нужно определить,
B>что такое документация в твоем проекте.

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

B>В нормальном проекте такие вещи (кто, когда и какие документы пишет)
B>должны оговариваться на этапе планирования, но это похоже не твой случай.

Это не мой случай, поскольку у нас долгое время было принято, что программист не только пишет программы, но и делает постановку задачи и объясняет тупому юзеру, как он должен работать (не только какие кнопки нажимать, а именно ЧТО он должен делать).
А сейчас новый руководитель банка хочет все это как-то систематизировать.

Re[2]: Кто должен писать документацию?

Здравствуйте, XMbIPb, Вы писали:

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

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

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

Re[3]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Я когда-то (года два назад) говорил с одним американцем, который в то время учился в колледже как раз по специальности technical writer. Ну и в общении с ним сделал такой вывод, что даже в том случае, если в фирме нет программистов, тех. документацию пишут как раз technical writers. И он очень долго не мог понять, что я таких очевидных вещей не понимаю, и что у нас такой специальности вообще нет. Он для этого в колледже 6 лет должен проучиться…

Похоже что есть проблема с понятиями «техническая документация» и «технический писатель».
Я могу сразу навскидку назвать несколько документов, которые на мой взляд (могу и заблуждаться )
являются техническими, но технический писатель врядли будет ими заниматься.
Например всевозможные планы (планы тестирования, СМ планы и прочее)
врядли имеет смысл поручать техническому писателю.
Спецификации системы, на мой взгляд, должен писать
именно разработчик (причем очень нехилой квалификации).
Дизайн системы, которые включает всевозможные диаграмы и схемы, — это тоже задача разработчика.

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

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

Re[4]: Кто должен писать документацию?

Здравствуйте, bkat, Вы писали:

B>Твой вопрос все же больше связан с планированием, в которое включается
B>определение ролей на проекте, исполнители, задачи, сроки выполнения задач и еще много чего…

Нет, ты не так понял (или я не так объяснил). Нужно в первую очередь написать именно инструкции пользователя, причем на уже имеющиеся задачи.
А уже позже заставят описывать внутренности программ, для того, чтоб программистов можно было увольнять безбоязненно.

Re[3]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

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

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

Re[5]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Нет, ты не так понял (или я не так объяснил). Нужно в первую очередь написать именно инструкции пользователя, причем на уже имеющиеся задачи.
E>А уже позже заставят описывать внутренности программ, для того, чтоб программистов можно было увольнять безбоязненно.

Скорей всего я понял тебе верно. Я рассуждаю теоретически.
А в твоем конкретном случае будет так, как скажет/сказал начальник

Re[4]: Кто должен писать документацию?

Здравствуйте, bkat, Вы писали:

B>Можешь на меня обижаться, но мудрый начальник увольняет таких людей при первом же подозрении

Ты случайно не начальник?

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

Re[3]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Это нужно для того, чтобы когда меня уволят, на моем месте легко справился бы другой программист.

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

E>Естественно, я не могу приветствовать это двумя руками.
Почему ? Ведь это вполне законное желание заказчика.
Исходники принадлежат работадателю (если отдельно не оговорено).
И заказчик диктует свои условия в данном случае.

… << RSDN@Home 1.0 beta 4 >>

Re[6]: Кто должен писать документацию?

Здравствуйте, bkat, Вы писали:

Спасибо тебе за быстрые ответы — я не успеваю новые вопросы печатать

B>Скорей всего я понял тебе верно. Я рассуждаю теоретически.
B>А в твоем конкретном случае будет так, как скажет/сказал начальник

Это я и сам понимаю. Мне только хотелось узнать, как это делается в других конторах, желательно в банках.

Re[7]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

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

… << RSDN@Home 1.0 beta 4 >>

Re[5]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Ты случайно не начальник?

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

Просто если ты думаешь, что запутанный код и отсутствие документации
укрепят твои позиции на работе, то ты здорово ошибаешься…

Re[6]: Кто должен писать документацию?

Здравствуйте, bkat, Вы писали:

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

Нет, я так не думаю. И не собираюсь так поступать. Я просто хотел сказать, что мне не интересно описывать внутренности своей программы, особенно если она давно написана. Ну нет у меня энтузиазма по этому поводу. А что-то скрывать… Смысла нет. Тем более, что в некоторых моих программах действительно никто не разберется (из тех, кто работает сейчас). Просто специфика программ такая. Ну и поэтому тем более не хочется описывать. Какой смысл? Программа умрет вместе с моим увольнением в любом случае. По хорошему нужно было сразу правильно делать постановку задачи, описывать алгоритмы, данные и т.д. Я на заводе немного проработал, так там именно так и делалось.

Re[4]: Кто должен писать документацию?

Здравствуйте, XMbIPb, Вы писали:

XMI>Еще это нужно, чтобы пользователи не бегали с вопросами к программеру: «А откуда эти цифры ???!!!» и вместо того, что бы мучительно долго вспоминать, что же там такого на самом деле, просто взять и ткнуть фейсом в бумаги.

Может быть у вас пользователи достаточно грамотные для того, чтобы понять документацию. А у нас многие не знают, что такое «Проводник». Смешно наверное звучит, но это так. Вообще, когда бардак и хочется этот бардак прекратить, трудно решить, с чего начинать. Нам наш управляющий сказал так: «Вы типа самые умные в банке, с вас и начнем». Т.е. какой смысл мучить простых исполнителей, когда они ничего вообще не понимают.

E>>Естественно, я не могу приветствовать это двумя руками.
XMI>Почему ? Ведь это вполне законное желание заказчика.

Я на этот вопрос попытался уже ответить. См. мой сегодняшний ответ bkat.

XMI>Исходники принадлежат работадателю (если отдельно не оговорено).

У нас в Украине все наоборот. Если дополнительно не оговорено в контракте, исходники и все права принадлежат автору. Такие у нас законы.

XMI>И заказчик диктует свои условия в данном случае.

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

Re[5]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>У нас в Украине все наоборот. Если дополнительно не оговорено в контракте, исходники и все права принадлежат автору. Такие у нас законы.

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

Re[6]: Кто должен писать документацию?

Здравствуйте, kong, Вы писали:

E>>У нас в Украине все наоборот. Если дополнительно не оговорено в контракте, исходники и все права принадлежат автору. Такие у нас законы.
K> Я тоже работаю программистом в банке и тоже на Украине.

В каком банке, если не секрет?

K> Когда меня брали на работу я подписывал трудовое соглашение, в нем оговорено, что все что я сделаю во время работы принадлежит банку. Так что посмотри свое трудовое соглашение, у тебя скорее все тоже так.

У меня вообще не было никакого трудового соглашения в том виде, как это понимается в законе о защите авторских прав. Так что формально я являюсь автором и мне принадлежат все права на мои продукты. Другое дело, что мне совершенно не интересны эти продукты. Они имеют смысл только внутри моего банка, а потому у меня в принципе не возникнет никакого желания «качать права». Да и в любом случае (чисто по-человечески и из соображений здравого смысла) я понимаю, что работодатель должен иметь бОльшие права на программы, чем программист, т.к. не будь этого работодателя не появились бы эти программы.

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

Возможно у вас больше порядка, чем у нас. У нас долгое время каждый разработчик сам придумывал, что ему делать, сам выбирал язык программирования, сам делал себе постановку задачи и т.д. Исполнители (те, кто пользуется программами) в большинстве случаев имеют настолько низкую квалификацию, что программистам приходится объяснять не только то, как пользоваться программой, а и то, ЧТО ВООБЩЕ должен делать исполнитель. Даже базовые понятия приходится объяснять, напр. что такое ОКПО или ключ в счете и т.д.

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

А я о чем? Я могу написать документацию. Но она будет понятна программисту. А пользователю — кто знает? Для меня, напр., очевидно назначение общепринятых пунктов меню. А для пользователя?

Re[7]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>Здравствуйте, kong, Вы писали:

E>В каком банке, если не секрет?

В Донецком региональном управлении ПриватБанка

E>Возможно у вас больше порядка, чем у нас. У нас долгое время каждый разработчик сам придумывал, что ему делать, сам выбирал язык программирования, сам делал себе постановку задачи и т.д. Исполнители (те, кто пользуется программами) в большинстве случаев имеют настолько низкую квалификацию, что программистам приходится объяснять не только то, как пользоваться программой, а и то, ЧТО ВООБЩЕ должен делать исполнитель. Даже базовые понятия приходится объяснять, напр. что такое ОКПО или ключ в счете и т.д.

Ну бардак у нас тоже знатный. Просто я работаю в отделе корпоративной сети и пишу программный комплекс для внутренних нужд (шеф хочет в перспективе получить нечто похожее на HP Open View ), поэтому у меня будут пользователи достаточно высокой квалификаци, а гланое понимающие что они хотят получить от программы.
Те кто пишет программы непосредственно для банковских нужд действительно вешаются, потому как наши работники зачастую имеют «очень» высокую квалификацию (правда сейчас у нас при приеме на работы ввели экзамен по начальным знаниям компьютера, так что хотя бы объяснять что такое мышь и виндоус уже не надо). Но у нас в банке есть такая практика: в основном все ПО пишется в головном банке, а в каждом подразделении есть несколько программистов, в задачу которых входит сопровождение программы на местах и борьба с пользователями. Так что разработчику в основном заниматься сексом с конкретными пользователями не приходиться, надо только объяснить все одному человеку (программисту подразделения), в се остальное это уже не его дело.

Re[7]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>……….. Другое дело, что мне совершенно не интересны эти продукты.

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

… << RSDN@Home 1.0 beta 6a >>

Re[7]: Кто должен писать документацию?

Здравствуйте, econt, Вы писали:

E>У меня вообще не было никакого трудового соглашения в том виде, как это понимается в законе о защите авторских прав. Так что формально я являюсь автором и мне принадлежат все права на мои продукты. Другое дело, что мне совершенно не интересны эти продукты. Они имеют смысл только внутри моего банка, а потому у меня в принципе не возникнет никакого желания «качать права». Да и в любом случае (чисто по-человечески и из соображений здравого смысла) я понимаю, что работодатель должен иметь бОльшие права на программы, чем программист, т.к. не будь этого работодателя не появились бы эти программы.

В соответствии с Российским законодательством:

Все имущественные права на программное обеспечение выполненое по заказу(читай указанию) работодателя принадлежат работодателю если иное не оговорено в договоре.
Все авторские права принадлежат автору.

Есть разница между имущественным и авторским правом.

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

Приятного чтения.

Если перед вами стоит вопрос – нужно ли вашему продукту пользовательское руководство, то отвечу сразу – да, нужно. Почему? На это есть две причины:

1. Качественная документация повышает лояльность клиента и ценность продукта в целом.

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

2. Руководство пользователя экономит время и силы техподдержки.

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

А теперь к советам!

Общие советы по созданию руководства пользователя

Прежде чем начинать писать руководство пользователя нужно ответить на несколько вопросов. — Для кого вы пишите? Кто будет пользоваться файлом справки? (ваша целевая аудитория)

— Где скорее всего пользователи будут прибегать к документации? (дома, на работе, в машине)

— Насколько объективно сложен для понимания продукт и как часто пользователь будет обращаться к документации?

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

(Для изложения лучше всего выбрать нейтрально-формальный стиль)

Структура руководства пользователя

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

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

В первом разделе расскажите общую информацию о продукте. Для чего создан проект и какие задачи он решает.

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

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

В любом руководстве желательны разделы «Частые вопросы» и «Устранение типовых проблем». Расскажите о проблемах, с которыми часто сталкиваются клиенты и о путях их решения.

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

И последний «обязательный» раздел, которой точно должен быть в любой документации – «контактная информация». Данный раздел даст пользователю возможность связаться с разработчиком. Если руководство вдруг не закрывает потребность читателя, то он может обратиться в поддержку. Кроме того, клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.

Профессиональный совет: если вы хотите максимально облегчить ношу клиента при чтении документации создайте контекстно-зависимую справку. Что это такое?

Представьте, что вы работаете в программе для создания пользовательской документации. Открываете меню основных настроек и видите раздел «аннотирование экрана» Заходите в него, там показаны разные стили аннотации, тени, фон и так далее. Но что такое аннотация? Допустим вы не знаете — нажимаете кнопку F1 и перед вами открывается руководство именно на той странице, где рассказано об «аннотировании экрана»

Как ее сделать? Смотрите ниже.

Контент

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

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

1. Понятность.

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

2. Наглядность.

Добавляйте в руководство побольше графики и скриншотов с аннотациями. Читателю будет проще и приятнее решать проблему, если будет наглядно показано как это делать.

3. Видео.

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

Но как добавить в документацию видео? Смотрите ниже.

Больше советов!

Когда документация будет готова, чтобы она стала «полноценной» её нужно опубликовать. Иначе какой от неё толк, если клиент не может её прочитать. У «юзера» всегда должен быть доступ к документации, и не важно где он. Такую потребность легко закрывают три формата: HTML, PDF и CHM.

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

Выложите руководство на сайт в формате HTML, чтобы клиент мог обратиться к документации, даже не работая с программой. Кроме того, документация, выложенная на сайт, повышает SEO факторы сайта.

И напоследок, переведите пользовательскую документацию в формат PDF, чтобы клиенты могли скачать и распечатать руководство.

Но помните, что после публикации документации, придется иногда её обновлять.

Инструменты

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

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

Dr.Explain – программа для создания руководств пользователя для ПО, web-сервисов и баз знаний.

Благодаря «доктору» вы сможете опубликовать и обновлять документацию в востребованных форматах (CHM; HTML; PDF; DOC), не выходя из программы.

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

Импортируйте в программу заранее написанные фрагменты документации.

Вы сможете создать контекстно-зависимую документацию, настроить визуальный стиль руководства, добавить в него видео и многое другое!

Какой можно сделать вывод

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

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

Работая с Dr.Explain, можно быстро написать пользовательскую документацию, которая будет помогать клиентам разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.

Спасибо за внимание!

Со всеми возможностями Dr.Explain можно ознакомиться здесь: