В теме 7 ответов, и 6 участников, последнее обновление сделано пользователем 
Михаил Сорокин 13 г, 8 мес. назад.
-
Сообщения
-
Интересно все: шаблоны документов, полезные советы, истории из собственной практики и тому подобное.Меня очень удивляет факт, что аналитики пишут руководства по эксплуатации. Объяснить могу только экономией или отсутствием тех.писа в команде (компании). Но это проза жизни, поэтому мы пишем
Ниже приведу статью, которую я начала писать для себя, но так и не закончила
Она сырая, но думаю польза в ней хоть какая-то есть.В последнее время у меня было несколько задач по написанию руководств пользователя.
По причине экономии, наверное, некоторые менеджеры придерживаются мнения, что ни один технический писатель не напишет «guide» лучше системного аналитика. Это ведь его детище, ему и писать. Я уже было подумала, что если совсем аналитический аппарат откажет, то подамся в писатели.
Вообще, прежде чем писать руководство самостоятельно, нужно перечитать пару-тройку готовых руководств к крупным системам. Например, к [url=http://office.microsoft.com/en-us/sharepointserver/CH100305421033.aspx]MS SharePoint[/url].
На мой взгляд существуют 2 цели написания руководств пользователя:
· Помочь пользователям разобраться с системой;
· И пусть будет, а вдруг пригодится (еще вариант – так надо).Вторая цель, вообщем, совсем не почетная. И в этом случае можно писать как бог на душу положит. Если, конечно, нет жесткого нормаконтроля, иначе какие-то минимальные требования к оформлению придется выдержать. Но, считаю – лучше ничего не делать, чем делать никак.
Чтобы достичь первой цели нужно выполнить 3 задачи ( это минимум конечно). Вполне достаточно сделать руководство читабельным, искабельным и запоминабельным.
Для выполнения первой задачи нужно иметь хороший слог и здравый ум. Очень хорошо будет сделать четкую структуру документа, прилично его оформить и не забыть про рисунки.
Со второй задачей поможет справиться опять же структура, содержание, теги, аккуратные ссылки, адекватные названия, словарь терминов и описание ролей.
С третьей сложнее, но можно использовать маленькие хитрости, например такие:
· Визуальная память у многих людей развита достаточно хорошо. Поэтому копии экранов системы, которые вставлены в правильные места в документе будут очень кстати.
· [url=http://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two]Правило «7+-2»[/url]. Если в каком-либо списке, разделе и т.п. больше 9 пунктов, то стоит его разделить на подразделы.
· Чем внимательнее человек читает, тем лучше он запомнит, то что он прочитал. Поэтому между строчками текста нужно оставлять достаточно пустого пространства, чтобы текст не сливался в серую массу. Этот прием помогает удерживать внимание пользователя. Но усердствовать тоже не стоит.
· Курсивный шрифт задерживает взгляд читателя дольше чем прямой. Про полужирное начертание, итак понятно.[size=150]Структура документа[/size]
В документе должен обязательно быть титульный лист с названием документа и системы, версией, автором, датой создания/обновления, статусом, содержание, история изменений и т.п.
Введение, на мой взгляд, является факультативным разделом. В нем можно зафиксировать цель документа, краткое описание, специфические правила оформления разделов и т.д.
Обязательный раздел документа – словарь терминов (глоссарий). В нем нужно указать все термины, которые хоть каким-либо образом претендуют на то, чтобы быть не понятыми.
Далее, основные роли системы. В этом разделе хорошо бы описать права доступа ролей к функциям и данным. Если ролевая структура системы соотносится с организационной структурой предприятия, то эту связь тоже нужно указать.
Так же в начале нужно описать общесистемные функции, если их можно выделить. К таким относятся аутентификация пользователя, системное меню, контекстное меню, «bulk-операции», фильтрация и сортировка списков, функции перехода между страницами списков, однотипные действия и т.д.
После всего этого можно приступать к описанию функциональностей системы. Тут есть 2 варианта. Структурировать документ, используя иерархию функциональностей системы или их ролевую принадлежность.
Выбрать нужный вариант можно следующим способом. Если система не большая и имеет достаточно четкий круг пользователей, то лучше описывать функциональности от ролей. Пример:
1. Руководство администратора
1. Учет пользователей
1. Регистрация пользователя
…
2. Руководство менеджера
1. …
Если функции нескольких ролей пересекаются, то достаточно описать их один раз, а потом везде упоминать с помощью ссылок на разделы документа.И соответственно, если система большая и предназначена для широкого круга пользователей, то лучше описывать функции с помощью иерархий. Пример:
1. Администрирование системы
1. Учет пользователей
1. Регистрация пользователя
…
2. Управление снусмумриками
1. …
В этом случае полезно ввести теги (ключевые слова) к функциям и организовать возможность поиска по тегам. А вот в тегах можно указать роли, которым доступна конкретная функция.[size=150]Оформление[/size]
Это может быть очень просто, если уже есть готовый корпоративный шаблон. Если шаблона нет, то нужно его сделать, хотя бы для себя. Рекомендую воспользоваться [url=http://ru.wikipedia.org/wiki/%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F]ГОСТ-ом[/url] (ГОСТ 34, ЕСКД, ЕСПД) и вспомнить опыт оформления курсовых и дипломных работ. Если нормаконтроля нет, то можно сильно не заморачиватся с ГОСТ-ами.
Во-первых, обязательно нужно нумеровать разделы документа и желательно выделять их цветом.
Во-вторых, должны быть подписи к изображениям и ссылки на них в тексте. Если нужно изобразить сложную последовательность действий, то можно сделать один «скриншот», а на нем с помощью [url=http://en.wikipedia.org/wiki/SnagIt]SnagIT-а[/url], например, указать порядок действий. А затем ссылаться так: «см. действие № 1 на рис.1.»
В-третьих, нужно делать отступы между изображениями и текстом, разделами документа, таблицами и текстом. Так же стоит выделять важные моменты в руководстве полужирным шрифтом.
Если в документе есть формулы, то их нужно оформлять с помощью специальных программ и выделять шрифтом (желательно курсивом). Очень важно нумеровать формулы. Если их мало в документе, то можно воспользоваться сквозной нумерацией, если же формул много, то нужно использовать нумерацию с учетом разделов.
Не надо злоупотреблять списками и таблицами. Большие таблицы и длинные списки очень тяжело воспринимать и читать.
[size=150]Содержание[/size]Содержание являет собой бритву Оккама. Важно описать все, что может пригодится пользователю, но не написать слишком много, чтобы пользователь прочитал.
Обязательно нужно описать все правила и ограничения, которые используются в системе. Если нужно привести формулы расчетов.
Так же нужно описывать все шаги пользователя и реакции системы, чтобы не вызвать у пользователя разрыв реальности =).
Но нужно помнить о том что не надо описывать все: кнопки и интерфейс например.
Если для выполнения какой-либо функции пользователю нужно сделать еще 20 то лучше нарисуйте это все красочной верхнеуровней диаграммой в начале главы.
В ней много ИМХО очевидных вещей, но хотелось собрать как можно больше инфы в одном месте =)
Essence, спасибо за заметки! Очень здорово и верно написано.
Я бы лично поставил под сомнение пару отдельных пунктов, но это только мое мнение.Меня очень удивляет факт, что аналитики пишут руководства по эксплуатации. Объяснить могу только экономией или отсутствием тех.писа в команде (компании).
Ага, согласен полностью — обычно срабатывают обе эти причины
. Но мне кажется, что это только в плюс аналитику — написание подобных доков помогает как познать нечто новое, так и развить в себе немного другой взгляд на документы и стиль их написания, ведь юзер гайд не есть спецификация и абсолютно не стоит при его создании пользоваться всеми до единого аналитическими рекомендациями по специфицированию требований. В документе должен обязательно быть титульный лист с названием документа и системы, версией, автором, датой создания/обновления, статусом, содержание, история изменений и т.п.
А мне кажется не стоит всего этого пихать в гайд. Документ должен быть по возможности простым в отличие от BRD, SRS, Vision и т.д. Я в свое время изучил определенное число юзер гайдов на продукты из разных областей и пришел к выводу, что титульник у гайда должен быть в первую очередь лаконичным и эстетически приятным. Я бы убрал такие пункты, как автор, даты, статусы и историю изменений — они не нужны конечным пользователям. Оставил бы только следующее: название системы, название документа, копирайт и содержание.
Далее, основные роли системы. В этом разделе хорошо бы описать права доступа ролей к функциям и данным. Если ролевая структура системы соотносится с организационной структурой предприятия, то эту связь тоже нужно указать.
Ну только если вкратце
. Не уверен, нужно ли обычному пользователю, который идя в начало документа хочет некое подобие getting started, детально расписывать весь механизм авторизации и аутентификации. Еще раз подчеркну, что юзер гайд — не спецификация, и как следствие труктура и стилистика должны быть почти противоположными оным в SRS. Юзер должен открыть док и по возможности, последовательно его читая, сразу начинать работать с системой, при этом не теряя интереса к самому доку. И начиная с основ он должен (при желании, конечно) углубляться все дальше и дальше.2. Управление снусмумриками
Ммм. Чем-чем?
Рекомендую воспользоваться ГОСТ-ом (ГОСТ 34, ЕСКД, ЕСПД) и вспомнить опыт оформления курсовых и дипломных работ. Если нормаконтроля нет, то можно сильно не заморачиватся с ГОСТ-ами
Если нормоконтроля нет, я вообще строго рекомендовал бы не заморачиваться с гостами. Чем креативнее и приятнее будет гайд, тем интереснее он будет для обычного человека.
От себя еще добавлю следующее (assuming, что юзер гайд идет на продукт, предполагающий значительную аудиторию пользователей, причем людей, вероятно неискушенных в тех. деталях):
1. Не забывать ставить копирайт — как вариант, в колонтитулах каждой страницы.
2. Легко различимая нумерация страниц.
3. Предпочтительно в колонтитулы помещать название текущей главы, предполагая, что пользователь будет печатать сий документ.
4. На мой взгляд не помешают иконки, визуально выделяющие такие, к примеру, штуки, как Примечание, Внимание! и т.д — наподобие того, как часто оформляют обучающие книги.
5. Язык не должен быть сложным и по возможности следует избегать технических терминов, даже кажущихся для вас элементарными.
6. Формат — имхо предпочтительнее PDF ибо никогда не знаешь, на какой платформе сидит пользователь.Всем книксен
Ага, согласен полностью — обычно срабатывают обе эти причины
. Но мне кажется, что это только в плюс аналитику — написание подобных доков помогает как познать нечто новое, так и развить в себе немного другой взгляд на документы и стиль их написания, ведь юзер гайд не есть спецификация и абсолютно не стоит при его создании пользоваться всеми до единого аналитическими рекомендациями по специфицированию требований. Самое прикольное, что при написании гайдов находишь свои ошибки и недочеты (то, что не додумал/не учел) с точки зрения аналитики.
А мне кажется не стоит всего этого пихать в гайд. Документ должен быть по возможности простым в отличие от BRD, SRS, Vision и т.д. Я в свое время изучил определенное число юзер гайдов на продукты из разных областей и пришел к выводу, что титульник у гайда должен быть в первую очередь лаконичным и эстетически приятным. Я бы убрал такие пункты, как автор, даты, статусы и историю изменений — они не нужны конечным пользователям. Оставил бы только следующее: название системы, название документа, копирайт и содержание.
Я бы поспорила по некоторым пунктам, но исключительно ради спора
Ммм. Чем-чем?
Снусмумриками
Рекомендую воспользоваться ГОСТ-ом (ГОСТ 34, ЕСКД, ЕСПД) и вспомнить опыт оформления курсовых и дипломных работ. Если нормаконтроля нет, то можно сильно не заморачиватся с ГОСТ-ами
Если нормоконтроля нет, я вообще строго рекомендовал бы не заморачиваться с гостами. Чем креативнее и приятнее будет гайд, тем интереснее он будет для обычного человека.[/quote]
Нет. ГОСТы — рулят. Во-первых, есть штатное место для "версий, копирайтов и т.д." (см. форматку по ЕСКД). Во-вторых, показывает серьёзность системы. И, наконец, повышает ЧСВ фирмы-разработчика.От себя еще добавлю следующее (assuming, что юзер гайд идет на продукт, предполагающий значительную аудиторию пользователей, причем людей, вероятно неискушенных в тех. деталях):
Вероятно речь идет о "продажном софте"? Типа TheBat? Например, в случае описаловок для прикладного ПО (хотя бы для автоматизации), имеет смысл рассчитывать на людей, искушенных в технических (а особенно — в технологических) деталях. Особенно с учетом того, что как-правило в ТЗ на подобные системы прописан уровень подготовки пользователя.
1. Не забывать ставить копирайт — как вариант, в колонтитулах каждой страницы.
2. Легко различимая нумерация страниц.
3. Предпочтительно в колонтитулы помещать название текущей главы, предполагая, что пользователь будет печатать сий документ.
4. На мой взгляд не помешают иконки, визуально выделяющие такие, к примеру, штуки, как Примечание, Внимание! и т.д — наподобие того, как часто оформляют обучающие книги.
5. Язык не должен быть сложным и по возможности следует избегать технических терминов, даже кажущихся для вас элементарными.
6. Формат — имхо предпочтительнее PDF ибо никогда не знаешь, на какой платформе сидит пользователь.1..3, 5 — согласен
4 — для книжек — да. Для UserGuide — IMHO работает только, если распространяется с "продажным софтом". И не применимо для "прикладного софта".
6 — так и хочется сказать, что "верстайте в TeXe (LaTeXe) — и будет вам счастьеЕсли есть заказчик, то читать его прежде всего будет он, так как его компанию будут оценивать по гайду, а не ту, куда отправили гайд для написания. Потому формальность/неформальность гайда должен определять непосредственно заказчик, если таковой имеется.Что касается написания гайда, то на месте новичка я бы выбрала компанию, которая в Ваших глазах явлется авторитетной и уважаемой и просмотрела бы созданными ими гайд с точки зрения оформления, структуры, креативности и формальности/неформальности документа и использовала бы понравившийся Вам (или заказчику) документ в качестве шаблона.
Есть такая книжка — MS Manual of Style for Technical Publications. В ней описано с большего всё, что нужно знать для написание доков для пользователей.
Я её как-то прочитал и с тех пользую как справочник. Всё очень предметно и без воды.
Книшку можно скачать интернетах. Если не найдете пишите в личку.
Вы должны авторизироваться для ответа в этой теме.
