Мануал туториал что это

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

	Мануал	Туториал
Определение	То же самое, что и руководство пользователя, то есть документ, который предоставляет людям помощь в использовании некоторой системы. Документ входит в состав технической документации , составляется техническим писателем.	Пошаговые инструкции как что-то сделать в виде электронного текста на сайте, в виде видео или аудио файле. Как правило, подготавливается пользователями, кто придумал, что либо нового и решил поделиться своими идеями с другими пользователями сети Интернет.
Где можно встретить?	В основном, можно скачать из интернета, также может прилагаться в виде печатной брошюры к программному продукту в магазине.	Можно встретить только в интернете.
В каком виде	В формате pdf и в печатном виде.	В виде постов на форумах, статьи на сайте, видео и аудио
	Мануал	Туториал
встречается?		файлах в сети интернет.
Структура	У инструкции всегда бывает оглавление, так как инструкция дает полное и исчерпывающее понятие о том, что это, и что с этим можно делать. Там описывается не одна операция, а сразу несколько. И, чтобы не запутаться в них, нужно оглавление.	У туториалов редко бывает оглавление, так как они обычно описывают какое — то одно действие, которое можно достичь путем выполнения всех пунктов туториала в представленной последовательности.
Стилистика текста	Документ готовится техническими писателями, поэтому стиль документа официальный.	Его пишут в основном молодые люди (от 18 до 40 лет) для пользователей сети интернет, поэтому язык туториалов смесь разговорного стиля с письменным.

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

1.4. Структура туториалов к графическим редакторам

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

teenslang.su
[17] дает
такое определение этому слову:

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

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

·
заголовок;

·
вводные
слова:

·
фото
результата;

·
поэтапная
инструкция как получить результат;

·
фото
результата;

·
заключительные
слова;

·
комментарии
пользователей.

Рассмотрим
эту структуру подробнее.

Заголовок

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

Вводные
слова.

Обычно
эта часть туториала состоят из следующих
абзацев:

-художественное
предисловие.
Например:
«Over
the years as a graphic designer I’ve accumulated a wealth of custom
brushes, shapes and actions that I keep carefully organized and
labeled for future use. The brush set I’ll be sharing with you
today has been in my collection for probably five of six years and
every once in a while I’ll find a good reason to load it into my
brushes palette. If you’ve never done that before, don’t worry,
I’ll walk you through it as we go.

If
you’re playing along at home you should
download
the
brush
set
before we get started».
[прил.
№1 п. 22]

—комментарии
переводчика (если урок переведен с
иностранного языка). «Это
моя первая проба пера в переводе
туториалов. Я постараюсь наилучшим
образом передать всю информацию
изложенную автором».
[прил. №1 п. 13]

Целеполагание
—
разъясняет пользователю, чему он
научиться, прочитав этот туториал.
Например:

«In
this Photoshop tutorial I am going to show you how to achieve a look
of a design or text that has been engraved or chiseled into stone or
any other material that you would like. It’s actually a quite easy
effect to achieve».
[прил.
№1 п.
8]

Фото
результата

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

Поэтапная
инструкция

В
толковом словаре Ушакова [24] «Инструкция
— это руководящие указания, подробное
наставление, свод правил для выполнения
чего-нибудь».
В словаре Ожегова «инструкция
— свод правил, устанавливающих порядок
и способ осуществления, выполнения
чего-н.»[6].
Это самые точные определение для этой
части в туториале. Только в туториале,
практически каждая текстовая команда
подкрепляется еще и графическими
объектами, так сказать промежуточными
результатами (принтскринами экрана
учителя). Сделано это для того, чтобы
пользователь мог сравнить свою поэтапную
работу с запланированными результатами.
Это необходимо для наглядности, так как
часто у пользователей разные версии
программы, для которой пишется урок.
Картинки помогают пользователю
соорентироваться, и не потерять ход
мысли тутора.

Фото
результата

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

Заключительные
слова

Это
неотъемлемая часть туториала и состоит
она из нескольких подпунктов:

-послесловие;

-прощание;

-автор;

-перевод
(ссылка на оригинал).

Комментарии
пользователей

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

Итак,
это структура стандартного туториала,
выложенного на форумах, посвященных
графическим редакторам: Adobe Photoshop и
Autodesk 3D Max. Естественно, каждый автор
текстового урока вносит в него, что-то
свое и немного изменяет структуру. Но
5 пунктов остаются всегда неизменными.
Это — название, вводные слова, инструкция,
заключение и комментарии.

Соседние файлы в предмете [НЕСОРТИРОВАННОЕ]

• #
• #
• #

  27.09.2019162.11 Кб052.rtf

• #
• #
• #
• #
• #
• #
• #
• #

For a tutorial on how to use Wiktionary, see Wiktionary:Tutorial.

English

Etymology

From Latin tutorius +? -ial.

Pronunciation

• (Received Pronunciation) IPA^(key): /tju??t?????l/
• (General American) IPA^(key): /tuw?t??ij??/, /t??t??ij??/
• (General Australian) IPA^(key): /t???to??i??/
• Rhymes: -?????l
• Hyphenation: tu?tor?i?al

Adjective

tutorial (not comparable)

1. Of or pertaining to a tutor; belonging to, or exercised by, a tutor.
   • 1959, Iona Opie, Peter Opie, The Lore and Language of Schoolchildren (page 363)

     The probability is that any verse of this nature, in which the lines are worn smooth, is one which has been causing tutorial ears to tingle for a generation at least; and very probably it is known in a variety of forms.

Translations

Noun

tutorial (plural tutorials)

1. A self-paced learning exercise; a lesson prepared so that a student can learn at their own speed, at their convenience.
2. An interactive class taught by a tutor to students at university or college, individually or in small groups.
3. (computing) A video or text that is basically a how-to (advice or instruction on a particular topic)

Translations

---

French

Etymology

From English

Pronunciation

• IPA^(key): /ty.t?.?jal/

Noun

tutorial m (plural tutoriaux)

1. Alternative form of tutoriel

---

Portuguese

Adjective

tutorial (plural tutorais, comparable)

1. tutorial

Noun

tutorial m (plural tutoriais)

1. tutorial (self-paced learning exercise)
2. (computing) tutorial (A video or text that is basically a how-to)

---

Spanish

Etymology

From tutor +? -ial.

Pronunciation

• IPA^(key): /tuto??jal/, [t?u.t?o??jal]

Adjective

tutorial (plural tutoriales)

1. tutorial

Noun

tutorial m (plural tutoriales)

1. (computing) tutorial (A video or text that is basically a how-to)

English

Alternative forms

• manuall (obsolete)

Pronunciation

• (UK) IPA^(key): /?man.j(?)?l/
• (US) IPA^(key): /?mænj?(w?)l/
• Hyphenation: man?u?al, man?ual
• Homophone: Manuel (Anglicized pronunciation)

Etymology 1

From Middle English manuel, from Old French manuel, from Late Latin manu?le (“handbook, manual”).

Noun

manual (plural manuals)

1. A handbook.
2. A booklet that instructs on the usage of a particular machine or product.

3. (military) A drill in the use of weapons, etc.
4. (Christianity, historical) An old office-book like the modern Roman Catholic ritual.

Synonyms

• enchiridion
• handbook

Derived terms

Descendants

• ? Japanese: ????? (manyuaru)

Translations

Etymology 2

From Middle English manuel, from Anglo-Norman manuel, Old French manual, from Latin manu?lis, from manus (“hand”).

Adjective

manual (comparative more manual, superlative most manual)

1. (of an activity) Performed with the hands.
2. (of a machine, device etc.) Operated by means of the hands.
3. (technology) Performed by a human rather than a machine.

Synonyms

• handly

Antonyms

• automatic

Coordinate terms

• aural, relating to the ear or the sense of hearing
• oral, relating to the mouth
• pedal, relating to the foot

Derived terms

Translations

Noun

manual (countable and uncountable, plural manuals)

1. (countable) A device that is operated using the hands, or by a human rather than a machine.
   1. (automotive) A manual transmission; a gearbox, especially of a motorized vehicle, shifted by the operator.
   2. (by synecdoche) A vehicle with a manual transmission.

   3. (music) A keyboard for the hands on a harpsichord, organ, or other musical instrument.
   4. A manual typewriter (as contrasted with an electronic one).
2. (countable) A procedure or operation that is done using the hands, or by a human rather than machine.
   1. (medicine, colloquial) Manual measurement of the blood pressure, done with a manual sphygmomanometer.

   2. A bicycle technique whereby the front wheel is held aloft by the rider, without the use of pedal force.
3. (uncountable) Manual control or operation.

   Put the controls to manual.

   Leave the system on manual.

Synonyms

• (automotive): stick shift / stick
• (automotive): standard transmission / standard

See also

(automotive):

• automatic
• semi-automatic
• manumatic

Translations

Further reading

• Manual on Wikipedia.Wikipedia
• Manual in the Encyclopædia Britannica (11th edition, 1911)

Anagrams

• alumna

---

Catalan

Etymology

Borrowed from Latin manu?lis.

Pronunciation

• (Balearic, Central) IPA^(key): /m?.nu?al/
• (Valencian) IPA^(key): /ma.nu?al/

Adjective

manual (masculine and feminine plural manuals)

1. manual

Derived terms

• manualment

Noun

manual m (plural manuals)

1. manual

Further reading

• “manual” in Diccionari de la llengua catalana, segona edició, Institut d’Estudis Catalans.
• “manual” in Gran Diccionari de la Llengua Catalana, Grup Enciclopèdia Catalana.
• “manual” in Diccionari normatiu valencià, Acadèmia Valenciana de la Llengua.
• “manual” in Diccionari català-valencià-balear, Antoni Maria Alcover and Francesc de Borja Moll, 1962.

---

Danish

Noun

manual c (singular definite manualen, plural indefinite manualer)

1. manual, a booklet that instructs on the usage of a particular machine

Inflection

---

Indonesian

Etymology

From English manual, from Anglo-Norman manuel, from Old French manual, from Latin manu?lis, from manus (“hand”).

Pronunciation

• IPA^(key): [ma?nu.al]
• Hyphenation: ma?nu?al

Noun

manual (first-person possessive manualku, second-person possessive manualmu, third-person possessive manualnya)

1. (colloquial) manual, handbook.

Adjective

manual (plural manual—manual)

1. manual,
   1. performed with the hands.
   2. performed by a human rather than a machine.

Further reading

• “manual” in Kamus Besar Bahasa Indonesia (KBBI) Daring, Jakarta: Badan Pengembangan dan Pembinaan Bahasa, Kementerian Pendidikan dan Kebudayaan Republik Indonesia, 2016.

---

Norwegian Bokmål

Etymology

Borrowed from Latin manualis, or English manual (“handbook”)

Noun

manual m (definite singular manualen, indefinite plural manualer, definite plural manualene)

1. a manual (handbook)
2. (music) manual (organ keyboard)
3. (weightlifting, fitness) a dumbbell

References

• “manual” in The Bokmål Dictionary.

---

Norwegian Nynorsk

Etymology

Borrowed from Latin manualis, or English manual (“handbook”)

Noun

manual m (definite singular manualen, indefinite plural manualar, definite plural manualane)

1. a manual (handbook)
2. (music) manual (organ keyboard)
3. (weightlifting, fitness) a dumbbell

References

• “manual” in The Nynorsk Dictionary.

---

Portuguese

Etymology

Borrowed from Latin manu?lis.

Pronunciation

• (Portugal) IPA^(key): /m??nwa?/

Adjective

manual m or f (plural manuais, comparable)

1. manual

Noun

manual m (plural manuais)

1. manual

---

Romanian

Etymology

Borrowed from French manuel, Latin manualis.

Pronunciation

• IPA^(key): /ma.nu?al/

Adjective

manual m or n (feminine singular manual?, masculine plural manuali, feminine and neuter plural manuale)

1. manual

Declension

Noun

manual n (plural manuale)

1. handbook

Declension

See also

• carte

---

Spanish

Etymology

Borrowed from Latin manu?lis.

Pronunciation

• IPA^(key): /ma?nwal/, [ma?nwal]

Adjective

manual (plural manuales)

1. manual (performed by the hands)
2. manual (operated by the hands)
3. manual (performed by a human)

   Antonym: automático

Derived terms

• de manual
• manualidad
• manualmente

Noun

manual m (plural manuales)

1. manual (handbook)
2. manual (booklet with instructions)

Further reading

• “manual” in Diccionario de la lengua española, Vigésima tercera edición, Real Academia Española, 2014.

---

Swedish

Noun

manual c

1. a manual, a handbook
2. (music) a manual, a keyboard

Declension

See also

• manuell
• pedal

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

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

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

• Продукты бывают сложные. Быстро разобраться и понять все их фишки без документации сложно или невозможно.

Документация помогает пользователю решить проблему или помочь разобраться с особенностями и фишками продукта. В любой документации люблю раздел Tips&Tricks.

Что входит в пользовательскую документацию

Пользовательская документация — это не юридические документы. У них другие цели.

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

Что еще можно отнести к пользовательской документации

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

В пользовательскую документацию я включаю:

• Ответы на часто задаваемые вопросы (FAQ).

• Руководство пользователя. Это самый жирный кусок из всей пользовательской документации. Здесь описывается весь интерфейс, только текстом.

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

• Описание отдельных фишек (Tips&Tricks). Чаще всего их делают в формате видеоуроков, но можно наткнуться и на текстовые.

• Релизноуты. Считаю их важной частью пользовательской документации. И, говоря релизноуты, я имею ввиду не разовые, которые выкладываются в магазины приложений или к себе на сайт. А написанные раз в какой-то период. Можно раз в месяц. При работе над прошлым продуктом мы писали всё, что исправили или добавили за месяц. Хорошим тоном, на мой взгляд, будет писать самое важное. 

• Видеоуроки. Считаю их частью пользовательской документации, но это скорее вкусовщина, чем правило.

Почему это важно?

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

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

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

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

Красоты B2B рынка

Прошлый продукт, над которым мы с командой работали, умел и в облако, и в on-premise.
С облаком все понятно. Динамическая документация на сайте или в другом сервисе. Документация для корпоративных заказчиков имеет определенные особенности. 

Особенность #1: Корпорации любят печатную документацию. Очень сильно.
Мой знакомый сейлз любит рассказывать истории про это. 

Резюме его историй:

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

Поэтому чем толще кипа бумаги — тем лучше.

Особенность #2: Нужно отдавать дополнительные пакеты документов.
В дополнительные пакеты документов входит: документация по установке вашего ПО и документацию по его администрированию, а может ещё что-то, если попросят.

Особенность #3: Документацию, которую вы отдаете корпоративному заказчику, нужно будет поддерживать отдельно. 
Реальность работы с большими корпоративными заказчиками в том, что ваш продукт требует доработки для решения их задач. Всегда есть какие-то нюансы и дополнения. Поэтому отдавать им облачную документацию, чаще всего, не получится.

Особенность #4: Встречается реже, но тоже требует внимания. Если ваш продукт визуально кастомизируется (меняются цвета, меняется расположение кнопок), то для каждого заказчика с нестандартным интерфейсом нужно будет делать свою документацию. Это не правило, а скорее хороший тон и забота.

Где делать?

Много думал, долго смотрел. Переделывал наш гайд раз пять.

Когда искал, ставил для себя следующие задачи:

• Документацию можно сделать динамической. То есть возможность грузить видео, гифки, делать кросс-ссылки.

• Поддерживается базовое форматирование: заголовки, жирный, курсив, code, code block.

• Возможность экспортировать в .pdf.

Небольшой совет

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

• Есть возможность выложить документацию на свой домен.

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

Какие вариант рассматривал:

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

• Google Docs.
  Стоимость: Free
  Плюсы: очень удобно работать с вёрсткой документа; привычный, при этом более простой интерфейс, относительно MS Docs; есть синхронизация с облаком; есть экспорт в .pdf.
  Минусы: очень тяжело работать с визуальной частью — скринами; отношу в категорию не динамичных, так как выложить ссылочку на сайт на Google Doc конечно можно, особенно учитывая их последние апдейты, но это выглядит как-то не серьезно. 

• Notion.
  Стоимость: можно Free, если работает один человек, а так от 8-10$ за человека.
  Плюсы: очень удобно делать динамическую документацию, которую не стыдно выложить на сайт, по моим ощущениям; удобно работать в паре, есть все необходимое; можно вставить любое медиа, хоть ссылку, хоть видео, хоть схему из miro.
  Минусы: не самый широкий спектр инструментов для работы с версткой; если неправильно сверстать, скопировать кусочек текста в другое место бывает накладно; не для всех пользователей привычная навигация по страницам.

• Другие инструменты для wiki. Я смотрел на несколько вариантов wiki.js, Stonly 2, Dropbox Paper, Outline. 

  Смотрел давно, поэтому ничего вразумительно сказать не смогу. Помню, только что из всего выше, зацепил Dropbox и Wiki.js. В процессе написания этой статьи наткнулся ещё на один интересный сервис — GitBook. Он удовлетворяет всем моим запросам к подобным инструментам, но прошел мимо меня когда выбирал. 

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

С чего начать?

Не скажу ничего нового.
Начинать нужно с ответа на вопрос «Зачем мы это будем делать?». Мы начинали писать первую версию как раз для корпоративного заказчика. Но эта итерация была небольшой. Писали краткий гайд.

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

После того, как поняли зачем, накидайте план, а точнеё оглавление. План подразумевает последовательность, а оглавление позволяет вам писать не последовательно. Я писал непоследовательно. Сначала писал то, что помнил на память, потом все остальное.

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

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

Основные правила

Понятный и простой язык

Я не буду писать о важности соблюдения правил русского языка: орфографии, пунктуации. И не буду рассказывать «Как писать хорошо?». Я сам далеко не эксперт в этом вопросе, поэтому когда мне нужно написать хороший текст я всегда обращаюсь к заветам Ильяхова и сервисам Главред, Яндекс.Спеллер и LanguageTools.

Любой текст должен быть простым и понятным.

Самое главное всегда это помнить.

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

Понятное и аккуратное форматирование

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

Правил много. Расскажу про самые бесячие и самые важные, на мой взгляд:

• Кавычки.
  Все то ли ленятся, то ли не знают где на клавиатуре находятся наши кавычки. У меня есть предположение, что эта привычка пошла со школ, потому что руками мы пишем другие кавычки. 

  Основные кавычки оформляются елочкой «», внутренние кавычки оформляются лапками „“. Например, «Нажмите на вкладку „Контакты“ в левом верхнем углу», забугорные кавычки выглядят так «_».

  

  P.S. Иностранные названия в русском тексте кавычками не выделяются. 

• Тире и дефис.
  Все знают про тире и дефис. Оказалось, что многие не знают про среднее тире.

  Дефис (-) используется для присоединения частиц (что-то), для присоединения префиксов (по-братски), в словосочетаниях и сложносоставных словах (бизнес-ланч).
  Среднее тире (–) применяется в числовом обозначении диапазонов и интервалов: 2011–2022, 11–12 ноября.
  Длинное тире (—) используется для выделения прямой речи, указания маршрутов (Москва — Санкт-Петербург), между подлежащим и сказуемым.

• Оформление списков.
  Существуют два вида списков: нумерованный и маркированный.

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

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

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

  Ещё один важный момент. 

  • Если пункт списка начинается с большой буквы, на конце всегда точка.

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

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

• Оформление дат и чисел.
  Если в тексте присутствуют даты, то лучше писать 15 мая 2021, а не 15.05.2021. Помогите пользователю думать только о важном.

  Если есть числа, то их нужно тоже оформить правильно. Не 2221, а 2 221. Отделяйте тысячные, это очень сильно упрощает восприятие.

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

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

• Буква Ё.
  С этой буквой у меня особые отношения. Исторически моя фамилия пишется через Ё, но из-за передергивания правил русского языка в советском союзе моя фамилия теперь пишется через Е. Поэтому я долгое время принципиально везде писал Е. Годы идут. Мозгов прибавилось. Теперь стараюсь писать Ё везде, где ей место. Так действительно проще воспринимать текст.

• Эмодзи в тексте ????
  По этому поводу много споров как у нас в команде, так и в кругах пишущих. Я придерживаюсь мнения, что эмодзи в тексте допустимы, но очень дозировано.

  Я использовал эмодзи для визуального подчеркивания каких-то кнопок в интерфейсе.
  Например: Нажмите на символ ⚙️ в правом верхнем углу.

  Для поиска символов пользуюсь Glyphy.

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

Если ваш продукт международный

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

Удобная навигация

Нет единого мнения — как правильно. Если самопис, я рекомендую делать вертикальную навигацию слева. Такая часто встречается в технических документациях.

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

• Блок общего и важного.

  • Описание вашего решения. Вдруг пользователь попал сначала на ваш гайд, а не на сайт.

  • FAQ.

  • Какие есть приложения, со ссылками на скачивания или как пользоваться, если это например веб-версия.

  • Наши обновления.

• Блок «Как начать». Сюда писать общие вещи, которые касаются всего сервиса. Особенно важный блок, если у вас мультиплатформенное решение.

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

  У нас, например, исторически разницы не было. Поэтому iOS и Android лежат на странице «Мобильные приложения». Но сейчас мы начали разделять, поэтому в будущем будет разделение на ОС.

Связность

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

Если хочется сделать по красоте, то можно внимательно изучить методологию Zettelkasten, например.

Удобный поиск

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

Вот как мы это в Notion решили.

Логичность

Всё, что вы пишите должно быть логичным. 

Порядок элементов в тексте и интерфейсе должен быть одинаковым. Пользователь ломается, когда написано: «Нажмите на вторую вкладку „Контакты“», а вторая вкладка — «Чаты». 
Или когда в интерфейсе элемент называется «Назначить админом», а написано «Назначить администратором». 

Понятная визуалка

Этот пункт я бы хотел разбить на два блока: работа с медиа и работа с Step-by-Step.

Работа с медиа

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

Иногда нет возможности сделать документацию динамической, особенно если вы работаете с корпоративными клиентами. Тогда делайте скриншоты реального интерфейса. Для этого лучше завести демо-стенд с близким к реальности наполнением. И там делать скриншоты.
Можно нарисовать демо-стенд в Figma и из этого собирать медиа для гайда. У меня такой подход не прижился, сложнеё управляться.

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

Очень не люблю стрелочки. Считаю, что лучше выделить место геометрической фигурой и поставить номер шага. Но иногда стрелочки приемлемы, тут вкусовщина.

Из хороших приемов — блюрить лишнюю часть интерфейса или делать выделение лупой важной части.

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

Step-by-step

Step-by-Step — это пошаговое описание всех действий, которые нужно выполнить пользователю, чтобы получить результат.

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

• Делать нумерованные списки. Если есть подпункты, то нумеровать их соответственно и делать сдвиг вправо 1.1, 1.2, 1.2.1 и тд.

• Писать сначала «Что нажать», потом «Где нажать». Исхожу из простой логики — сначала нужно понять «Что искать» и только потом «Где искать».

  Например: «Нажмите на кнопку „Включить“ в правом верхнем углу», а не «В правом верхнем углу нажмите на кнопку „Включить“».

• Вставлять визуальные элементы для кнопок, особенно если они без подписи. Для этой истории приходится немного костылить, если делать это в том же Notion, но в Google Docs это делать проще. Использую стандартные эмодзи и сервис Glyphy.

  Например: Нажмите на символ ⚙️ в правом верхнем углу.

  Не люблю слово иконка, поэтому пишу символ, чтобы была однозначность. Тоже вкусовщина.

• Если одно действие можно сделать из разных мест, описывать все места и каждое по пунктам.

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

• Все названия кнопок, сущностей, элементов — должны иметь такое же название как в интерфейсе.

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

Поддержка и послесловие

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

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

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

Раз в 3-6 месяцев заходить и перечитывать, лучше если это каждый раз будет делать новый человек. Это нужно делать по трем причинам:

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

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

3. Всегда есть что улучшить. Текст это такой же продукт.

Хочется верить, что эта статья сэкономит кому-то время, а кому-то поможет стать немного лучше.
Я не претендую на истину в последней инстанции. Описал свой опыт и мнение.

p.s. Пользовательская документация с которой все началось. Скажу сразу, там очень много чего можно и нужно улучшить. Бэклог по апдейту документации уже перевалил за 30 задач. Постепенно обновляем.

p.s.s. буду благодарен за конструктивный фидбек в комментариях и ещё больше, если поделитесь вашим опытом. 

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

И прилагательное, и существительное

Английское прилагательное tutorial (произносится с ударением на «о») имеет два значения: «наставнический» и «опекунский».

А вот что такое «туториал», когда это слово выступает как существительное:

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

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

Молодежь знает лучше

Урок, поэтапно объясняющий определенный процесс, содержащий подробную инструкцию достижения какого-то конкретного результата, — вот что такое туториал.

Есть несколько видов туториалов:

• видео;
• графический;
• текстовый.

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

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

Как достигнуть эффективности

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

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

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

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

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

Туториалы для художников и всех-всех-всех

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

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

Какие еще бывают туториалы для художников? К примеру:

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

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

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

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

M>Мануал, хэлп/хелп, референс и туториал?

Частично эти понятия перекрываются; кроме того, они могут быть и определителями друг для друга (напр. reference manual).
Но все же (наиболее рекомендуемые варианты перевода — жирным шрифтом):

M>Manual — справочник, пособие, руководство в зависимости от самого мануала
Руководство, (краткий) справочник, описание, (краткая) инструкция.
Не обязательно строго формальная документация; является либо единственным документом, описывающим систему; либо представляет собой часть документации, описывающую систему только с одной стороны:
User(‘s) manual — руководство пользователя
Servicing manual — руководство по обслуживанию (устройства)

Отдельно нужно упомянуть reference manual — справочное руководство. Типично — краткое и формализованное описание системы, небольшого объема.

M>Help — справка, справочная система?
Здесь в зависимости от употребления вариантов много.
(Контекстная, контекстно-зависимая) справка, помощь; справочная система.
Представляемая на экране информация небольшого объема по одному конкретному вопросу; организованная система таких небольших справок.

M>Reference — руководство, справочное пособие
Справочник. Перевод «руководство» считаю неверным.
Строго формальное и обычно полное описание системы либо ее компонента.
Programmer’s reference — справочник программиста
C++ language reference — справочник по языку C++
(P.S. Не путать с другими значениями слова reference — например, «ссылка»)

M>Tutorial — пошаговое руководство
Учебник, учебное пособие (совсем необязательно пошаговое).
Обычно построено в форме, близкой к ответам на вопрос «как?», не претендует на сколь-либо полное описание системы.

К Вашему списку можно добавить еще
Guide — руководство.
По значению более близко к Manual, но слово воспринимается как имеющее более «поверхностный» характер.
Quick-reference guide — краткая инструкция
User(‘s) Guide — руководство пользователя

Все, что здесь сказано, может и будет использоваться против меня…

Мануал, хэлп/хелп, референс и туториал?

Manual — справочник, пособие, руководство в зависимости от самого мануала

Help — справка, справочная система?

Reference — руководство, справочное пособие

Tutorial — пошаговое руководство

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

[skip]

Нет слов. Великолепно