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

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

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

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

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

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

Ryzhij писал(а):

DelSnos писал(а):
Реально потребовать соблюдения всех пунктов договора можно лишь тогда, когда в руководстве заказчика нет афилированных генподрядчику лиц.
В противном случае неизбежно возникает ситуация:
«Составьте перечень недостатков и претензий!
Составили?
Молодцы!!! А теперь идите и думайте, как вы будете это устранять. Сроку вам — до вчерашнего утра…»

Так бывает очень часто когда заказчик и подрядчик родом из СНГовии.
Если речь идет за АБОК (первоначально вопрос пришел оттуда), где для управления вентиляторами и регистрами действительно все просто и шкаф рождает проектант, а изготовитель радостно его набирает, а монтажник прибивает к стенке (что фактически постоянно вижу у холодильщиков/вентиляционщиков) то разуемеется проектант и выдает весь комплект эксплуатационки, правда эту доку разве что обнять и плакать можно.
Но если вести речь о оборудовании более сложном или более, скажем так, эксклюзивном, что имет место быть в промышленности то зачастую проектант рисует общие мысли — конструкторы теоретики создают нечто, которое после наладки на объекте не похоже совсем на первичное решение (зачастую это нормализованные входа-выхода к физике с защитами и прочим, а все что не имеет видимого ответа стыдливо прячется под личину контроллера, мол там программер на наладке как то это оживит), в таком случае РЭ и КД выдает организация наладчик, разумеется после длительных препираний с разработчиком, по поводу распила. Или не выдает если сторговаться с разработчиком не удалось.

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

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

	От:	econt	http://cprime.110mb.com
Дата:	03.01.03 17:21
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

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

	От:	bkat
Дата:	03.01.03 17:57
	Оценка:

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

	От:	XMbIPb
Дата:	03.01.03 18:10
	Оценка:

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

	От:	econt	http://cprime.110mb.com
Дата:	03.01.03 18:27
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

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

	От:	econt	http://cprime.110mb.com
Дата:	03.01.03 18:38
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

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

	От:	bkat
Дата:	03.01.03 18:41
	Оценка:	8 (1)

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

	От:	econt	http://cprime.110mb.com
Дата:	03.01.03 18:45
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

	От:	bkat
Дата:	03.01.03 18:48
	Оценка:	8 (1)

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

	От:	bkat
Дата:	03.01.03 18:51
	Оценка:

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

	От:	econt	http://cprime.110mb.com
Дата:	03.01.03 18:52
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

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

	От:	XMbIPb
Дата:	03.01.03 18:53
	Оценка:

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

	От:	econt	http://cprime.110mb.com
Дата:	03.01.03 18:55
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

	От:	XMbIPb
Дата:	03.01.03 19:03
	Оценка:

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

	От:	bkat
Дата:	03.01.03 19:05
	Оценка:

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

	От:	econt	http://cprime.110mb.com
Дата:	04.01.03 05:40
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

	От:	econt	http://cprime.110mb.com
Дата:	04.01.03 05:49
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

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

	От:	kong
Дата:	04.01.03 06:44
	Оценка:	12 (1)

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

	От:	econt	http://cprime.110mb.com
Дата:	04.01.03 08:06
	Оценка:

Мне никогда не нравилась MFC. (c) Charles Petzold

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

	От:	kong
Дата:	04.01.03 08:30
	Оценка:

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

	От:	Stoune
Дата:	02.04.03 22:28
	Оценка:

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

	От:	Vampire
Дата:	03.04.03 07:41
	Оценка:	12 (1)

Если долго мучиться что нибудь получится

Как написать руководство пользователя программы или сайта — инструкции, советы, помощь, программное обеспечение

Журавлев Денис

Что такое руководство пользователя и для чего его создавать

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

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

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

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

После этого важно подумать о том:

• Где пользователь будет к нему обращаться: дома, на работе, в машине?
• Как часто он будет его просматривать?
• Насколько объективно сложен для понимания продукт?

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

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

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

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

В первом разделе желательно рассказать общую информацию о программе:

• Для чего создан продукт.
• Какие задачи он решает.
• Какие основные выгоды от использования для клиента.

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

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

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

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

Инструменты для быстрого создания руководства пользователя

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

Одним из популярных инструментов для создания качественного руководства является программа Dr. Explain (https://www.drexplain.ru), в которой уже есть готовые шаблоны руководств пользователя с готовой структурой разделов и в которой удобно обновлять документацию, как бы часто эти обновления не происходили.

Видео-обзор основных возможностей программы Dr.Explain

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

Любой проект в Dr.Explain вы можете создать с нуля или импортировать уже существующую документацию, например из формата MS Word, HTML или CHM-файла, и буквально за несколько минут создать из нее онлайн-помощь, файл справки в формате CHM, или документ в формате PDF.  

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

У программы свой собственный редактор, оптимизированный под работу со сложной документацией. Основные функции редактора вынесены в компактный тулбар. Это — управление стилем текста, форматирование абзацев, вставка ссылок, изображений, видео, таблиц и списков, а также вставка специальных объектов. Dr. Explain экономит время и силы своих пользователей. Разработчики документации часто сталкиваются с проблемой многократного использования одного и того же фрагмента текста и прибегают к очевидным решениям — «Ctrl+c», Ctrl+v». Dr.Explain предлагает решение по повторному использованию контента — текстовые переменные. Это решение экономит время, когда нужно много раз использовать один и тот же текст, особенно, который может периодически изменяться — например, версия документируемой системы.

Многие российские компании сталкиваются с тем, что руководство пользователя нужно писать согласно ГОСТ 19 и ГОСТ 34. Dr.Explain активирует поддержку требований ГОСТ фактически одним кликом. Программа автоматически сформирует структуру обязательных разделов и установит требуемые параметры страницы, стили абзацев, списков и заголовков.

Часто техническим писателям при документировании пользовательского интерфейса приходится снабжать изображения пояснительными выносками. Для таких случаев программа поддерживает специальные графические объекты — аннотированные экраны. Чаще всего аннотируются скриншоты программ и страниц веб-сайтов. Уникальной особенностью Dr.Explain является автоматическая аннотация изображений, получаемых при захвате экранов с окнами программ или сайтов. Программа анализирует структуру окон и добавляет пояснительные выноски ко всем значимым элементам.

Кроме того, Dr.Explain позволяет нескольким авторам одновременно работать над проектом с использованием сервиса www.tiwri.com, учетную запись на котором можно создать бесплатно за пару минут. При внесении правок одним автором сервис блокирует редактируемые разделы проекта для изменения другими авторами.  По окончании редактирования изменения отправляются на сервер, и блокировка снимается. Так несколько человек могут одновременно работать над различными разделами проекта без риска помешать друг другу.  

Попробовать режим многопользовательской работы в Dr.Explain можно даже с бесплатной лицензией. Вы можете создать общий проект и полноценно работать с ним в многопользовательском режиме до семи дней.

Почему компании выбирают Dr.Explain для создания руководств пользователя

Павел Свиридов, профессиональный военный, полковник, создатель астрологической системы «Вега Матрица»

«Только программа Dr.Explain обладала всеми необходимыми возможностями. А главное — она давала простор для творчества. Можно было выбрать цветовую гамму, вид и форму служебных элементов, настраиваемые шаблоны. Это позволило мне сохранить стилевое единство документации и самой программы. Ну, и конечно, полуавтоматическая обработка материала существенно облегчает и ускоряет работу по созданию хелпа.

Обучение работе в Dr.Explain было наглядным и сделано возможностями самой программы, что безусловно повлияло на мой выбор в ее пользу».

Прочитать полный кейс компании «Вега Матрица вы можете перейдя по ссылке

---

Наталья Обухова, бизнес-аналитик компании CRM Expert

«По классике жанра был пилотный проект на двух фаворитах (Dr.Explain и HelpNDoc) и муки выбора.

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

Сначала фаворитом выбора была другая система, но решающим фактором в пользу Dr.Explain стал возглас человека, выполняющего основную часть работы по переносу текста: «Вжух! И вся структура документа перенеслась в файл справки». Функция импорта в Dr.Explain отработала на ура и сэкономила кучу времени.

Также очень подкупил дизайн веб-справки, который формируется Dr.Explain, и красивый способ организации подписей к окнам нашей системы. В Dr.Explain это называется «Аннотирование экрана».

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

Прочитать полный кейс компании CRM Expert

---

Николай Вальковец, разработчик компании 2V

«Мы значительно сократили время работы техподдержки с новыми клиентами на этапе подключения. Раньше требовалось проводить онлайн презентации и видео конференции для новых клиентов, объясняя особенности программы. Сейчас же, один раз постаравшись максимально подробно всё описать, мы избавили себя и нашу техподдержку от этой работы. Нам импонирует простота программы и скорость работы. Можно быстро редактировать, добавить новые пункты в документацию, сохранить в формате HTML и выложить на сайт».

Прочитать кейс компании V2  

---

Подытожим

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

Скачать Dr.Explain с неограниченной по срокам возможностью бесплатной работы можно по адресу: https://www.drexplain.ru/download/

Успешных вам разработок!

Смотрите также

• Dr.Explain — инструмент для создания мобильной версии пользовательской документации к программным продуктам
• Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний — бесплатные шаблоны и примеры пользовательской документации

Одним из важных этапов на проекте внедрения 1С является обучение сотрудников новой программе. Этап становится довольно «болезненным», если заказчик не согласен на обучение. Тогда рассматривается альтернативный вариант – написать руководства пользователей.

В этой статье я поделюсь опытом написания инструкций на проекте внедрения 1С. Расскажу, как писать ПОНЯТНЫЕ руководства пользователей, и главное – как внедрить в компании регламент для сотрудников.

Руководство пользователя – это технический документ, который предназначен для оказания поддержки пользователям конкретной системы. В этом смысле используется и слово «мануал» (manual).

Рассмотрим основной алгоритм написания инструкций для пользователей программы 1С.

1. ОПРЕДЕЛЯЕМ ТЕМУ И ЦЕЛЕВУЮ АУДИТОРИЮ

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

• Инструкция для конкретного блока учета в программе, например, «Инструкция по блоку Продажи»,

• Инструкция для определенной должности сотрудника, например, «Инструкция для менеджера по оптовым продажам»,

• Инструкция по конкретной функции или процессу, например, «Инструкция по маркировке товаров».

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

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

2. ПРОДУМЫВАЕМ СТРУКТУРУ СОДЕРЖАНИЯ

Для выстраивания взаимосвязи разделов важно знать и понимать набор процессов и последовательность их действий. Разобраться в этом помогут:

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

• Проектное решение – это документ, состоящий из методологического проектного решения, которое фиксирует функциональный объем проекта – определяет какие действия и сущности будут «покрыты» функционалом информационной системы, а также технического проектного решения, которое фиксирует объем, принципы и описание доработок конфигурации 1С и является основой для дальнейшей доработки – изменения типовых и создания новых объектов конфигурации 1С.

• Встречи с заказчиком.

Инструкция по блоку. Заголовок раздела – объект программы.

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

Инструкция для должности. Заголовок раздела – название процесса.

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

Инструкция по процессу. Заголовок раздела – название процесса, объекта программы, должности.

Пример: процесс – реализация маркированных товаров. Менеджер по продажам создает реализацию товаров, выгружает данные на терминал сбора данных, затем кладовщик на складе считывает товары на терминал сбора данных и заносит их в 1С. Тогда структура содержания может выглядеть следующим образом:

3. ПИШЕМ ИНСТРУКЦИЮ

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

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

Подробная или не очень

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

Если пользователь ранее работал в подобных программах, например, менеджер по продажам имеет опыт работы с программой 1С: Управление торговлей 11, тогда ему будет не сложно заполнить нормативно-справочную информацию и создать документы «Заказ клиента» и «Реализация товаров и услуг». Такая инструкция будет содержать меньше конкретики.

Полнота изложения

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

Ветвления

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

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

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

Заголовки – это обязательно.

Позволяют «просканировать» ваш текст и остановиться сразу на нужной части. Но главное – не нарушать их иерархию.

Абзацы – это не так просто.

Есть универсальное правило: одна мысль – один абзац. Он не должен быть огромным, чтобы не перегружать информацией. Но и делать абзац из одного предложения тоже не стоит. Оптимальная длина – 5 строк.

Списки – это удобно и понятно.

Маркированный список – это обычный список перечисления с маркерами, точками. В перечне элементы не упорядочены между собой. От их перестановки местами смысл не поменяется.

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

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

1) Перейдите в раздел Закупки – Документы закупки (все).

2) Нажмите кнопку «Создать – Приобретение товаров и услуг – Закупка через подотчетное лицо».

3) Укажите на вкладке «Основное» следующие данные:

•  Организация,

•  Поставщик,

•  Контрагент,

•  Договор,

•  Склад.

4) Заполните вкладку «Товары».

5) Укажите на вкладке «Доставка» способ доставки.

6) Нажмите кнопку «Провести и закрыть».

Наглядность. Японское правило: «Одна картинка стоит тысячу слов».

Скриншоты 

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

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

Делюсь удобными и бесплатными инструментами для создания скриншотов:

• Lightshot. Скачать можно тут.

• Яндекс.Скриншот, входит в состав утилиты Яндекс.Диск. Посмотреть можно тут.

Важные фрагменты текста

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

Пример: Обратите внимание!!! Обычный менеджер не сможет отредактировать график оплаты в соглашении c клиентом. Для этого предусмотрена отдельная роль. Если данный функционал не доступен, то необходимо обратиться в ИТ-отдел.

Экспертность. Автор обязан хорошо разбираться в теме.

Если так вышло, что описываемый блок программы – новая тема для аналитика, тогда за основу типового функционала рекомендую взять инструкции с официального сайта 1С: ИТС.

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

Актуальность.
Инструкцию придется периодически обновлять.

Если порядок действий, интерфейс программы, который вы описываете, меняется, то инструкцию нужно обновлять. Вопрос – кто должен это делать?

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

4. ПРОВЕРЯЕМ, ПРОВЕРЯЕМ И ЕЩЕ РАЗ ПРОВЕРЯЕМ

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

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

КАК ВНЕДРИТЬ ИНСТРУКЦИИ ДЛЯ СОТРУДНИКОВ

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

Правило №1. Должностные папки

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

Правило №2. Проверка знаний

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

Правило №3. Контроль выполнения

Служба ИТ-отдела должна проверять, как на самом деле выполняются регламенты в компании. Понятно, что мы не можем тратить на это много времени и ресурсов. Здесь нужно здравомыслие: просто устраивайте проверки с определенной периодичностью.

ПОДЫТОЖИМ. Для того, чтобы написать качественную инструкцию нам нужно:

1. Определить тему и целевую аудиторию.

2. Продумать структуру содержания.

3. Написать инструкцию, соблюдая следующие критерии:

• Содержательность,

• Структурированность,

• Наглядность,

• Экспертность,

• Актуальность.

4. Проверить инструкцию под правами пользователя.

Чтобы правильно внедрить регламент, необходимо соблюдать три правила:

1. Регламент попал к сотрудникам, и вы в этом убедились.

2. Сотрудник его прочитал, понял и прошел проверку знаний. 

3. Соблюдение регламента контролируется.