Кратком руководстве quick guide

Краткое руководство по началу работы или руководство по быстрому запуску ( QSG ) — это, по сути, сокращенная версия руководства , предназначенная для того, чтобы как можно скорее познакомить покупателя с его или ее продуктом . Это подразумевает использование краткого пошагового подхода, который позволяет покупателю использовать продукт без каких-либо задержек, при необходимости включая соответствующие шаги, необходимые для установки. Краткое руководство по началу работы, или сокращенно QSG, фокусируется на наиболее распространенных инструкциях, часто сопровождая такие инструкции простыми для понимания иллюстрациями . Внешний вид QSG может значительно отличаться от продукта к продукту и от производителя к производителю. Например, это может быть отдельный лист формата А4, сложенная карточка или буклет, состоящий всего из нескольких страниц.

Задний план

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

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

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

Требования

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

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

• Гид пользователя
• Техническая коммуникация
• Технический писатель

Ссылки

3

1. ВВЕДЕНИЕ

В кратком руководстве (Quick Guide) пошагово объясняют—

ся основные операции с устройством.

А сейчас уделите несколько минут для ознакомления с

данными инструкциями по применению. Таким образом

вы сможете обеспечить безопасность и сохранность при-

бора. Светодиоды и индикаторы на панели вашей маши-

ны помогут вам правильно взаимодействовать с ней:

Не горит —

Горит Функция

доступна

Мигает Текущая

функция

Быстро мигает

Устройство

требует

вмешательства

пользователя

Эти символы также используются в кратком руководстве

(Quick Guide), прилагаемом к изделию.

2. ПРИ ПЕРВОМ ИСПОЛЬЗОВАНИИ

• Инструкции по первому запуску машины приведены

в КРАТКОМ РУКОВОДСТВЕ (QUICK GUIDE).

• При первом включении необходимо подать 4–5 пор-

ций, прежде чем машина начнет выдавать удовлет—

ворительный результат.

• При первом включении гидросистема пуста, поэ-

тому машина может издавать повышенный шум.

Шум будет уменьшаться по мере заполнения

гидросистемы.

• Возможные следы кофе в кофемолке появились там

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

жу. Они свидетельствуют о скрупулезных проверках,

которым подвергается изделие.

3. ВКЛЮЧЕНИЕ И ВЫКЛЮЧЕНИЕ

• При каждом включении прибор автоматически вы-

полняет цикл предварительного подогрева и опо-

ласкивания, которые нельзя прерывать. Машина

будет готова к использованию только после выполне-

ния такого цикла.

• Если до этого готовился кофе, каждый раз при выклю-

чении выполняется автоматическое ополаскивание.

Опасность ожога!

Во время ополаскивания из носиков узла подачи кофе вы-

ходит некоторое количество горячей воды. Следите за тем,

чтобы на вас не попали брызги воды.

СОДЕРЖАНИЕ

1. ВВЕДЕНИЕ ……………………………………… 3

2. ПРИ ПЕРВОМ ИСПОЛЬЗОВАНИИ ………… 3

3. ВКЛЮЧЕНИЕ И ВЫКЛЮЧЕНИЕ …………… 3

4. ПРИГОТОВЛЕНИЕ КОФЕЙНЫХ НАПИТКОВ 4

4.1 Приготовление

кофе из

кофейных зерен

……………………………………………………… 4

4.2 Приготовление кофе из предварительно

молотого кофе ………………………………..4

4.3 Изменение вкуса кофе …………………….. 4

4.4 Ополаскивание ……………………………….4

4.5 Советы по приготовлению более горячего

кофе ……………………………………………….4

4.6 Регулировка кофемолки ………………….. 4

4.7 Настройка

количества напитка в

чашке 5

5. ПРИГОТОВЛЕНИЕ КАПУЧИНО ……………. 5

6. ИЗМЕРЕНИЕ ЖЕСТКОСТИ ВОДЫ …………. 5

7. ФИЛЬТР ДЛЯ СМЯГЧЕНИЯ ВОДЫ ………… 6

7.1 Замена фильтра ……………………………….6

7.2 Удаление фильтра…………………………….6

8. РЕКОМЕНДАЦИИ ПО ЭНЕРГОСБЕРЕЖЕНИЮ

…………………………………………………….. 6

9. МЕНЮ НАСТРОЕК …………………………….. 7

9.1 Сброс к заводским настройкам ………… 9

11. ОЧИСТКА ЗАВАРОЧНОГО УЗЛА …………..10

12. УДАЛЕНИЕ НАКИПИ …………………………11

13. ЗНАЧЕНИЕ СВЕТОВЫХ ИНДИКАТОРОВ …12

14. УСТРАНЕНИЕ НЕИСПРАВНОСТЕЙ ……….14

Edit me

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

Необходимость в кратких справочных руководства

Будь то документация для конечного пользователя или документация для разработчика, в кратком справочном руководстве содержится 1-2-страничное руководство, где кратко описаны основные задачи и функции системы.

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

Текст в диаграмме приведен на латинице по соображениям конфиденциальности, поэтому логика может быть не совсем очевидной. Но в этом API конечные точки организованы в разные группы. Некоторые из групп имели несколько уровней в конечной точке, и несколько опций включения для каждой конечной точки. Диаграмма была создана в Adobe Illustrator и опубликована в формате PDF. Разработчики сочли такой формат полезным, потому что был охвачен API в целом, показав, как все конечные точки соединены друг с другом в логической гармонии. Для документации API обычное дело, что в кратком справочном руководстве перечислены сокращенные описания конечных точек. По этой причине вывод Swagger UI часто может служить кратким справочным руководством.

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

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

Преимущества чистой информации для изучения

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

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

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

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

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

Задача, вероятно, невозможна для технического материала. Тем не менее, попытка того стоит, и философия остается прежней. Краткие справочные руководства научат нас пользоваться системой за 5 минут, а не за 5 часов. Это философия упрощения и языковой эффективности.

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

Примеры краткого руководства

Ниже приведены примеры кратких справочных руководств на различных сайтах документации по API.

Eventful

Eventful предоставляет быстрый список всех конечных точек в API на одной странице, упорядоченный по группам ресурсов. Каждая конечная точка описана примерно в половину строки, поэтому можно быстро понять их все. Например, описание для /events/get в их кратком справочнике: «Получить запись о событии». Но если щелкнуть для получения более подробной информации, более подробное определение будет «При наличии идентификатора события возвращает данные о событии, связанные с этим событием». , См. http://eventful.com/events/E0-001-000278174-6 для примера интерфейса».

С первого взгляда на конечные точки можно получить определенное понимание. Взглянув с высоты на лес, можно увидеть форму леса в целом. Можно не знать, какие деревья содержит лес, но можно понять другие детали, которые не видны, когда видишь одно дерево.

Parse

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

Иногда разработчикам нравится одностраничный подход, потому что он уменьшает фрагментацию информации и позволяет им использовать Ctrl + F, чтобы найти все экземпляры ключевого слова. Исследования компромиссов такого одностраничного подхода описаны в Single-page docs versus “Click Insanity”.

При использовании справочной документации OpenAPI на GitHub, заметно, что документация также содержится на одной странице. Разработчики могут использовать Ctrl + F, для быстрого поиска. Тем не менее такая документация обеспечивает много визуальной сложности для понимания пользователям.

Shopify

Краткое руководство Shopify не про API, но оно показывает фильтры, переменные и другие функции, доступные в Liquid, который является языком сценариев для разработчиков. Здесь Shopify использует функциональность свертывания и расширения для сжатия информации.

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

👨‍💻 Практическое занятие: краткое справочное руководство

В своем найденном опен-сорс проекте найдем краткое справочное руководство. Ответим на следующие вопросы:

1. Существует ли краткое справочное руководство по API? Возможно, список конечных точек API?
2. Есть ли вывод Swagger UI, который служит кратким справочником по API?
3. Если нет краткого справочного руководства, выиграет ли API от этого? Почему да или почему нет?
4. Помимо списка сокращенных описаний конечных точек, что еще можно добавить в краткое справочное руководство API? Общие задачи?
5. Есть ли несколько важных задач, которые пользователи должны выполнять с помощью API? Обсуждаются ли эти основные задачи в руководстве по началу работы?

🔙

Go next ➡