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

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

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

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

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

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

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

Картинка с сайта: habr.com

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Картинка с сайта: habr.com

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

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

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

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

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

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

Итого:

Картинка с сайта: habr.com

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

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

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

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

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

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

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

See you soon!

Руководство пользователя нужно всем IT-продуктам — новым и давно выпущенным. Куда нажать, чтобы всё заработало? Как пользоваться программой после масштабного обновления? Знакомые вопросы для любого юзера.

Рассказываем, каким бывает руководство пользователя, и как написать свой юзер-гайд по опыту WEEEK.

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

📌 Руководство пользователя ещё называют инструкция пользователя, документация, хелп или юзер-гайд (user guide). Это справочная цифровая библиотека, по которой можно изучать программу. Руководство пользователя входит в состав технической документации и разрабатывается техническим писателем и продуктовой командой.

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

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

⚙️ Пошаговое руководство или «Быстрый старт»

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

Картинка с сайта: weeek.net

Источник: Segnetics

⚙️ Справочное руководство

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

Картинка с сайта: weeek.net

Хелп WEEEK

⚙️ Руководство по устранению неисправностей

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

Картинка с сайта: weeek.net

Источник: ELTEX

⚙️ Руководство для администраторов

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

Картинка с сайта: weeek.net

Источник: VK WorkSpace

⚙️ API-документация

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

Картинка с сайта: weeek.net

Источник: REST API GitHub

Руководства такие разные, но у них много общего — структура, язык, подход к написанию. 

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

Как создать руководство пользователя. Опыт WEEEK

Технический писатель и автор раздела «Помощь» WEEEK Рукия Багаудин рассказала, как устроено наше руководство изнутри, и поделилась полезными инструментами, которые помогают вести и обновлять его. 

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

Шаг 1. Определение содержания

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

К примеру, руководство пользователя в WEEEK содержит подробную информацию о пяти главных сервисах: Задачах, Базе знаний, CRM, Пользователях и Аналитике.

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

Картинка с сайта: weeek.net

Слева как раз содержание руководства: главные его части

Шаг 2. Структурирование материала

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

Здесь нужно расширить содержание сервиса. Как это сделать? Разбить составные части продукта на более мелкие — определить разделы и статьи, которые расскажут про каждый из них.

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

💡 При визуализации лучше дать каждому блоку свой цвет — это поможет  ориентироваться в структуре и видеть картину целиком:

Картинка с сайта: weeek.net

Построение схемы в FigJam

Картинка с сайта: weeek.net

Главное договориться о цветах визуализации!

Шаг 3. Написание и форматирование

Написание статей можно поставить на поток. Достаточно подготовить шаблон и собирать тексты как конструктор:

Картинка с сайта: weeek.net

У нас структура текста документации создана в FigJam

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

Каждая колонка на Канбан-доске может относиться к разделам хелпа: 

Картинка с сайта: weeek.net

Структура на доске повторяет структуру в схеме. Но с доской проще работать

То же самое касается и самого написания статей.

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

Ответственный перемещает задачу по доске. Когда текст готов, то его переносят в колонку «На проверке» — и так далее. Это делает процесс работы прозрачным.

Картинка с сайта: weeek.net

Рукия Багаудин, технический писатель WEEEK 

Картинка с сайта: weeek.net

На Канбан-доске удобно декомпозировать большие задачи. Так можно повторить структуру руководства со схемы — все внутренние подразделы привязаны к родительскому. Они образуют одну сущность, будут храниться вместе и не потеряются:

Картинка с сайта: weeek.net

Глава руководства — задача. Статьи — подзадачи

Картинка с сайта: weeek.net

Шаг 4. Ревизия и корректура

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

Для этого тексты должна проверять продуктовая команда — продакт-менеджер, владелец продукта или отдел контента, при условии, что он погружен в продукт.

Шаг 5. Публикация и актуализация

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

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

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

Тезисы вместо всей статьи