Мануал текста что это

Здравствуйте, уважаемые читатели блога: My-busines.ru. Из содержания
предлагаемой вашему вниманию статьи вы сможете узнать о том, что такое мануал.

Что это такое

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

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

Для чего нужен

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

Формат

Наиболее распространенными являются следующие форматы: PDF, Word, HTML. Рассмотрим каждую из этих разновидностей форматов более подробно.

PDF-формат наиболее распространен, потому как он является межплатформенным. Изначально данный формат был создан фирмой Adobe Systems с использованием специального языка PostScript. Наиболее подходящей программой для открытия данного формата является Adobe Reader.

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

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

Как
составить (написать, сделать) мануал

Написание грамотного мануала включает в себя следующие этапы:

1. Указание темы. В границах и сфере темы необходимо быть предельно внимательным и точным;
2. Определение аудитории, для которой составляется (новички, профессионалы, люди со средними знаниями, будут ли изучать самостоятельно или же коллективно);
3. Выбор количества разделов;
4. Выбор названий разделов;
5. Выбор логической структуры изложения материала. Взаимосвязь разделов должна определяться исходя из последовательности действий;
6. Составление словаря терминов, если планируется использование специальных жаргонизмов. Его необходимо будет обновлять по мере написания;
7. Определение тем, которые требуют дополнительного исследования. Если вы не уделите подготовке мануала должного внимания, то от него не будет абсолютно никакой пользы. По этой причине очень важно закончить проведение различного рода дополнительных исследований до того, как вы приступите к написанию;
8. Определение структуры каждого из разделов;
9. Организация логической последовательности каждой секции и каждого раздела, постепенно сужая границы темы.

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

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

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

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

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

Проверять готовый мануал лучше всего в следующей
последовательности:

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

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

Что такое мануал?

Категория:
Что такое?

– Автор:
Игорь (Администратор)

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

Мануал (Manual) — это, в ИТ сфере, руководство пользователя по использованию какой-либо программы, сервиса и тому подобного. Если говорить простыми словами, то это нечто вроде «инструкции для чайников» или «инструкции по применению».

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

В каких ситуациях применяется термин мануал? Чаще всего слово мануал совмещают с такими словами как «смотри», «читай», «изучай» и подобными. Как бы указывая пользователю, что решение проблемы можно найти в документе и, в ряде случаев, что не стоит пытаться «повесить» свои проблемы на других людей (обычно, из-за лени).

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

Тем не менее, стоит знать, что у данного термина существуют иные значения. Например, под словом «мануал» могут подразумевать клавиатуру органа.

Так же советую ознакомиться с обзором Как правильно задавать технические вопросы.

Понравилась заметка? Тогда время подписываться в социальных сетях и делать репосты!

☕ Понравился обзор? Поделитесь с друзьями!

Добавить комментарий / отзыв

Здравствуйте, уважаемые читатели блога: My-busines.ru. Из содержания
предлагаемой вашему вниманию статьи вы сможете узнать о том, что такое мануал.

Что это такое

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

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

Для чего нужен

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

Формат

Наиболее распространенными являются следующие форматы: PDF, Word, HTML. Рассмотрим каждую из этих разновидностей форматов более подробно.

PDF-формат наиболее распространен, потому как он является межплатформенным. Изначально данный формат был создан фирмой Adobe Systems с использованием специального языка PostScript. Наиболее подходящей программой для открытия данного формата является Adobe Reader.

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

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

Как
составить (написать, сделать) мануал

Написание грамотного мануала включает в себя следующие этапы:

1. Указание темы. В границах и сфере темы необходимо быть предельно внимательным и точным;
2. Определение аудитории, для которой составляется (новички, профессионалы, люди со средними знаниями, будут ли изучать самостоятельно или же коллективно);
3. Выбор количества разделов;
4. Выбор названий разделов;
5. Выбор логической структуры изложения материала. Взаимосвязь разделов должна определяться исходя из последовательности действий;
6. Составление словаря терминов, если планируется использование специальных жаргонизмов. Его необходимо будет обновлять по мере написания;
7. Определение тем, которые требуют дополнительного исследования. Если вы не уделите подготовке мануала должного внимания, то от него не будет абсолютно никакой пользы. По этой причине очень важно закончить проведение различного рода дополнительных исследований до того, как вы приступите к написанию;
8. Определение структуры каждого из разделов;
9. Организация логической последовательности каждой секции и каждого раздела, постепенно сужая границы темы.

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

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

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

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

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

Проверять готовый мануал лучше всего в следующей
последовательности:

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

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

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

А

Что такое аватар?
Аватар (аватарка) — небольшая картинка в профиле, на форуме или в комментариях, отображающая личность и характер пользователя.

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

Что такое апдейт?
Апдейт (ап), (с англ. update) — модернизация; корректировка; обновление информации, данных — пополнение базы данных поисковой машины новой информацией. Другими словами, индексирующий робот поисковиков в течении определенного времени накапливает информацию о различных ресурсах в своей базе данных. Когда информация из базы данных переносится в основную базу, происходит апдейт. После апа вы можете проверить тИЦ и PR своего сайта, возможно, эти показатели стали выше.

Б

Что такое бан?
Бан, быть забаненным — лишиться доступа к чему-либо. Можно быть забаненным на форуме, т.е. запрет на общение и просмотр тем. Можно быть забанненым в поисковиками — запрет на индексацию.

Что такое блог?
Блог (от англ. blog, от web log) — персональный дневник или журнал с записями временной значимости. Другими словами, небольшой сайт на домене третьего уровня.

Что такое браузер?
Браузер — веб-обозреватель, программное обеспечение для просмотра веб-страниц. Самыми популярными в настоящее время являются Internet Explorer, Mozilla Firefox и Opera.

Что такое буксы?
Букс — это часть САР, т.е. сервис, на котором зарабатывают с помощью кликов на рекламе рекламодателей. Рекламодатель размещает за определенную плату на буксе рекламу в виде ссылки на свой сайт. Пользователь просматривает определенное время сайт и получает вознаграждение.

В

Что такое валидный код?
Валидный код (Valid) — действительный, правильный HTML-код, написанный с соблюдением всех правил и стандартов, который легко читать браузеру. Валидный XHTML гораздо лучше индексируется поисковыми роботами.

Что такое валидатор?
Валидатор — программа, которая проверяет наличие в HTML-документе нарушений спецификации, согласно которой составлен документ, если эти нарушения там действительно есть.

Г

Что такое говноблог (говносайт)?
Говноблог — это блог, не представляющий интереса для пользователя, созданный либо для «мыслей вслух» либо для заработка на рекламе. Г-блог часто заполнен сворованным контентом либо нередактированным переводом с другого языка. Такие блоги не имеют конкретной тематики -«всё обо всём».

Д

Что такое домен?
Домен — это имя веб-страницы в сети Интернет, его можно увидеть в адресной строке. Каждый домен уникален, повторяющихся нет. Домены бывают первого, второго и третьего уровней (обычно разделяют точками). Например, ru — домен первого уровня, blogger.com — второго, ty-blogger.blogspot.com — третьего.

И

Что такое индексация сайта?
Индексация сайта — это процедура по внесению данных о страницах вашего сайта или блога в базу поисковых систем, совершаемая поисковым роботом. После индексации страницы вашего блога (сайта) могут быть показаны в результатах поиска.

К

Что такое контент?
Контент (англ. content — содержание) — информационно значимое наполнение сайта или блога, т.е. это могут быть: текст, изображения, мультимедиа и др. Важными параметрами контента являются уникальность, актуальность и объем.

Что такое копирайт?
Копирайт — эмблема или надпись, заявляющая об авторском праве на ресурс. Чаще всего проставляется внизу веб-страницы.

Что такое копирайтинг?
Копирайтинг — это написание рекламных слоганов или презентационных текстов на заказ. Часто понимается как деятельность по созданию уникального контента для сайта или блога.

Что такое куки?
Кука (куки, cookie, cookies) — файл, который сохраняется на жестком диске при каждом посещении какой-либо веб-страницы. Куки сохраняют данные о пользователе (например, IP или логин и пароль) и сообщающие о возвращении пользователя спустя какое-то время. Другие сайты не могут читать чужие куки.

М

Что такое мануал?
Мануал (с англ. руководство) — подробная инструкция по использованию программного обеспечения или железа.

О

Что такое оффтоп?
Оффтоп (офтоп, офтопик, off topic) (от англ. — «вне темы») — сообщение не по теме.

П

Что такое программное обеспечение?
Программное обеспечение (ПО, софт) — это компьютерные программы для обработки и передачи различной информации, необходимые для использования этих программ.

Что такое пузомерки?
Пузомерки (от «мерить пузо») — показатели, по которым вебмастера сравнивают достижения своих сайтов или блогов. Наиболее значимыми пузомерками являются тИЦ и PR.

 Р

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

Что такое реферал?
Реферал (от англ. referral — ссылочный) — участник какого-либо веб-ресурса, зарегистрировавшийся по вашей ссылке. За счет привлечения реферала вы получаете свой процент от его прибыли.

С

Что такое сайдбар?
Сайдбар — это боковая вертикальная колонка сайта или блога. Также сайдбаром называют вертикальную часть окна браузера, в которой можно увидеть закладки.

Что такое сайт?
Сайт (от англ. website: web — «паутина», «сеть» и site — «место», т.е. «место в сети») — это комплекс документов и другой информации, объединенных одним доменным именем.

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

Что такое сателлит?
Сателлит — это вспомогательный сайт, помогающий раскрутке основного сайта, т.е. это веб-ресурс, который ссылается на ваш сайт.

Что такое серфинг?
Серфинг (англ. surfing — скольжение по волнам) — это последовательный просмотр веб-страниц за вознаграждение.

Что такое софт?
Софт (от англ. software) — то же самое, что и программное обеспечение.

Что такое спам?
Спам — это ненужная не запрашиваемая информация, чаще всего носящая рекламный характер.

Т

Что такое тИЦ?
тИЦ (тематический индекс цитирования) — показатель поисковика Яндекс, характеризующий авторитетность веб-сайта. Определяется количеством внешних ссылок на этот веб-ресурс.

Ф

Что такое фавикон? Фавикон — иконка веб-сайта, отображаемая в адресной строке браузера, в результатах поиска в поисковиках и в закладках некоторых браузеров.

Что такое флейм? 
Флейм (с англ. Flame — вспышка) — эмоциональные всплески на форумах и чатах, выкрики, наезды, в общем, ругань.

Что такое флуд?
Флуд (с англ. flood— наводнение) — пустословие, большие сообщения на форумах, не несущие никакой информации.

Что такое фриланс?
Фриланс (с англ. freelance — внештатный сотрудник, свободный работник) — удаленная работа без контракта, поиск работы и ее выполнение через интернет.

Что такое футер?
Футер (англ. footer — подвал) — часть веб-сайта, находящаяся в самом низу станицы.

Х

Что такое хост?
Хосты — это количество уникальных IP-адресов, просмотревших веб-станицу.

Что такое хостинг?
Хостинг (с англ. web-hosting, collocation) — это размещение веб-сайта на каком-то веб-сервере, т.е. каждый сайт не просто плавает в интернете, а закреплен на определенном сервере. Хостинг бывает платный и бесплатный.

A-Z

Что такое HTML?

HTML (Hyper Text Markup Language) — язык разметки гипертекста, т.е. это единый язык, с помощью которых создаются веб-сайты, одинаково понимаемый всеми компьютерами.

Что такое IP-адрес?
IP-адрес (ай пи – от Internet Protocol) — это личный номер, присваиваемый компьютеру или другому устройству при первом доступе в интернет. Служит для определения адресата передачи данных, и от кого поступает запрос.

Что такое PR?
PR (англ. Page Rank) — это рейтинг поисковой системы Google, показатель, характеризующий значимость страницы сайта или блога в сети.

Чтобы найти ответы на любые вопросы, касающиеся сотовой связи или мобильных телефонов, посетите форум сотовых телефонов 
Узнай все о прекрасном городе Лондон на сайте Туристер.ру.
PROhelp в г.Киев осуществляют ремонт компьютеров быстро и по доступным ценам.

Что такое мануал?

Категория:
Что такое?

– Автор:
Игорь (Администратор)

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

Мануал (Manual) — это, в ИТ сфере, руководство пользователя по использованию какой-либо программы, сервиса и тому подобного. Если говорить простыми словами, то это нечто вроде «инструкции для чайников» или «инструкции по применению».

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

В каких ситуациях применяется термин мануал? Чаще всего слово мануал совмещают с такими словами как «смотри», «читай», «изучай» и подобными. Как бы указывая пользователю, что решение проблемы можно найти в документе и, в ряде случаев, что не стоит пытаться «повесить» свои проблемы на других людей (обычно, из-за лени).

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

Тем не менее, стоит знать, что у данного термина существуют иные значения. Например, под словом «мануал» могут подразумевать клавиатуру органа.

Так же советую ознакомиться с обзором Как правильно задавать технические вопросы.

Понравилась заметка? Тогда время подписываться в социальных сетях и делать репосты!

( 3 оценки, среднее 4.67 из 5 )

Что такое мануал

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

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

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

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

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

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

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

мануа́л

1. муз. клавиатура органа или клавесина для игры руками ◆ На его месте построили новый, восьмигранный, похожий на осьминога Концертный Зал, и соорудили в нём самый современный орган с тремястами регистрами и пятью мануалами. Л. В. Кириллина, «Сказка о Фуге, Органе и Доме с Привидением»

2. проф. то же, что мануальный терапевт ◆ В общем, сходите сначала к врачу, а потом уже к мануалу, или к массажисту.

3. комп. жарг. руководство пользователя ◆ Человеку, ремонтирующему сложную технику, окажется полезным сервис мануал, выпускаемый для конкретных устройств. Газаров А. Ю., «Устранение неисправностей и ремонт ПК своими руками», 2011 г. (цитата из библиотеки Google Книги)

---

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

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

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

Определить целевую группу

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

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

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

• Если аудитория состоит из людей старшего поколения, то используйте хорошо читаемый разборчивый шрифт. 
• Если же она представлена разработчиками, то нет необходимости объяснять базовые шаги в ОС Windows. 
• Если вы пишите для дислексиков, то делайте предложения короткими и используйте простые термины.

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

Понять, как будет использоваться продукт 

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

Вот два примера, которые помогут выделить отличия этих двух принципов.

• Функционально-ориентированное название главы: “Использование мастера экспорта”.
• Задачно-ориентированное название главы: “Экспортирование данных проекта”.

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

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

В этом случае рекомендуется спросить себя следующее.

• Что будут делать пользователи с продуктом?
• Почему они его используют? Какова их цель?

Лучше всего будет пригласить группу пользователей и провести с ними обсуждение. Целью будет определить их задачи и, в идеале, дать им название на языке пользователей. Если же возможности собрать группу реальных пользователей у вас нет, то есть еще одно решение: пригласить коллег, которые по своей работе близко с ними связаны (например, продакт-менеджеров, проектных менеджеров, маркетологов или специалистов поддержки).

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

Начните с инструкций

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

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

Советы по написанию инструктивных глав

Вот несколько советов, которые нужно учесть при написании инструктивных глав.

• Начинайте название главы с существительного. Пример: “Экспортирование данных проекта”.
• Структурируйте инструктивные главы в виде нумерованного списка. Каждый этап задачи должен представлять один пункт списка.
• Инструктивная глава не должна превышать 11 шагов. Большее число шагов излишне ее удлинит, снизив удобство чтения. Если в итоге у вас получается длинная глава, то поделите ее на подразделы.
• Описывайте шаги в императивной форме. Пример: чтобы экспортировать данные проекта, нажмите на значок “Экспорт”.
• Не предоставляйте подробной информации о возможности продукта или о том, как он работает. Вместо этого сосредоточьтесь на выполняемых пользователем шагах. Главы с сопутствующей информацией относятся к следующему этапу руководства.

Далее приводится пример того, как должна быть отформатирована и написана инструктивная глава.

Пример инструктивной главы

Добавление сопутствующей информации

После написания инструкций спросите себя: “Что нужно знать пользователям (чего они еще не знают) для выполнения всех этих инструкций?”

Перед каждой инструктивной главой добавляйте концептуальные. Они будут объяснять особенность ПО, необходимую для выполнения инструкций. В примере “Экспортирование данных проекта” одна глава может быть посвящена мастеру экспорта и поддерживаемым форматам данных.

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

Советы по написанию сопутствующей информации

Вот несколько советов, актуальных при написании концептуальных глав.

• Не добавляйте в заголовках описательные приставки типа “О…” или “Сведения о…”. Называйте только сам принцип или функцию, которую хотите описать. Почему? Когда вы ищете что-либо по теме в интернете, то не вводите “Сведения о затмении”. С большей вероятностью вы будете искать по запросу “Затмение”. Когда пользователи ищут принципиальную информацию, они действуют аналогично, например пишут запрос “Мастер экспорта”.
• Добавляйте только такие концептуальные главы, которые помогут пользователям выполнить инструкцию. Вероятно, вы вложили немало усилий в разработку бэкенда, необходимого для работы конкретной функции. При этом сложности, связанные с ее реализацией, не должны отражаться в документации. Единственное исключение  —  когда пользователю нужно знать эти детали для выполнения инструкций. Перед написанием концептуальной главы всегда спрашивайте себя: “Зачем пользователю нужно это знать?”.
• Связывайте описательные главы с соответствующими инструктивными и наоборот.

Пример главы с сопроводительной информацией

Добавление справки

Последний компонент  —  это справка. Справочные главы содержат информацию для поиска в виде таблиц. В этих таблицах вы описываете графический интерфейс пользователя (GUI) и API.

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

Советы по написанию справочной информации

• Заголовок справочной главы должен совпадать с элементом GUI или описываемой в ней функцией, например “Диалоговое окно мастера экспорта”.
• Обязательно называйте элементы GUI так же, как они названы в самом GUI. Пользователи зачастую копируют названия элементов и вставляют их в строку поиска.
• Подумайте, какая информация поможет пользователю, ищущему конкретный элемент GUI. Возможно, он как-то связан с другими элементами GUI или ограничениями. Задокументируйте их в справочной главе.

Примеры справочных глав

---

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

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

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

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

Помните, что мануалы мы читаем не ради удовольствия, а от необходимости.

Читайте также:

• 5 вредных привычек неэффективных программистов
• Как написать хороший README: краткий курс
• Успешный релиз ПО: распространенные ошибки перед запуском продукта

Читайте нас в Telegram, VK и Яндекс.Дзен

---

Перевод статьи Andreas D.: How To Write Manuals as a Developer