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. Карта позволяет узнать все существующие функции.
👨💻 Практическое занятие: краткое справочное руководство
В своем найденном опен-сорс проекте найдем краткое справочное руководство. Ответим на следующие вопросы:
- Существует ли краткое справочное руководство по API? Возможно, список конечных точек API?
- Есть ли вывод Swagger UI, который служит кратким справочником по API?
- Если нет краткого справочного руководства, выиграет ли API от этого? Почему да или почему нет?
- Помимо списка сокращенных описаний конечных точек, что еще можно добавить в краткое справочное руководство API? Общие задачи?
- Есть ли несколько важных задач, которые пользователи должны выполнять с помощью API? Обсуждаются ли эти основные задачи в руководстве по началу работы?
🔙
Go next ➡
Ресурсы по теме
В США большинство результатов лабораторных исследований приведены в так называемых условных единицах; остальное население планеты фиксирует результаты в Système International d’Unités (СИ) или в международных единицах (МЕ). База единиц измерения в СИ периодически обновляется с помощью коллегии.
Многие единицы измерения в СИ такие же, как и единицы измерения, используемые в американской системе; однако единицы измерения концентраций в СИ отличаются. Концентрация в СИ определяется в молях (моль) или в долях моля (например, миллимоль, микромоль) на единицу объема, выраженную литрами (л). Традиционные единицы измерения определяются как отношение массы (например, граммов, миллиграммов) или химической емкости (например, миллиэквивалентов) к единице объема, выраженного в литрах или десятых частях литра (например, децилитрах, миллилитрах). Результаты, представленные количеством, содержащимся в 100 мл (1 дл), иногда выражаются в виде процента (например, 10 мг/дл может быть записано как 10 мг%).
Моли, миллиграммы и миллиэквиваленты: один моль – это число Авогадро (6,023 × 1023) элементарных частиц (например, атомов, ионов, молекул); масса 1 моля вещества – это его атомная масса в граммах (например, 1 моль натрия = 23 г, 1 моль кальция = 40 г). Подобным образом, отношение массы данного количества вещества к его атомной массе определяется как число молей (например, 20 г натрия = 20/23 (или 0,87) моль).
Эквивалент – это единица, которая интегрирует заряженные частицы и выражается в молях; 1 эквивалент представляет собой 1 моль заряженного вещества и рассчитывается путем умножения числа молей заряженных частиц на их валентность. Таким образом, для ионов с зарядом +1 или −1 (например, Na+, К+, Cl−), 1 моль – это 1 эквивалент (1 × 1 = 1); для ионов с зарядом +2 или −2 (например, Са2+), ½ моля – это 1 эквивалент (½ × 2 = 1), и так далее для других значений валентности. Миллиэквивалент (мЭкв) – это одна тысячная часть эквивалента.
Ниже приведены формулы, которые могут быть использованы для преобразования мЭкв, мг и ммоль друг в друга:
мЭкв = мг/молекулярная масса × валентность = ммоль × валентность
мг = мЭкв × молекулярная масса/валентность = ммоль × молекулярная масса
ммоль = мг/молекулярная масса = мЭквнутривенноалентность
(ПРИМЕЧАНИЕ: молекулярная масса = атомная или молекулярная масса по формуле соединения)
Кроме того, таблицы преобразования доступны в печатном виде и в интернете.
ПРИМЕЧАНИЕ:
Это — Профессиональная версия.
ПОЛЬЗОВАТЕЛИ:
Просмотреть пользовательскую версию
Авторское право © 2023 Merck & Co., Inc., Rahway, NJ, США и ее аффилированные лица. Все права сохранены.
перейти к содержанию
manuals.plus представляет собой сборник руководств пользователя, инструкций, технических паспортов и спецификаций для электронной продукции. Мы ежедневно добавляем новые руководства в нашу коллекцию, создавая легко доступную для поиска базу данных по электронным ресурсам.
Обычно справочные листы для устройств содержат спецификации, инструкции по сбросу и базовую справку по использованию. Некоторые инструкции расширяют этот вопрос и содержат советы по ремонту и обслуживанию, другие могут быть сокращенным набором «советов по быстрому запуску» — важных вещей, которые вам нужно знать, чтобы приступить к работе с устройством.
Руководства пользователя обычно предоставляются в формате PDF, но этот формат может быть трудно использовать на мобильном устройстве или при подключении с низкой пропускной способностью. Manuals.plus утомительно транскрибирует многие из этих PDF-документов в обычный формат. web-страницы, чтобы пользователи могли лучше читать их на любом устройстве. Это делает многие документы более доступными для чтения с экрана и поиском по сравнению с традиционным форматом. Помимо транскрибированного сообщения, вы также найдете ссылку на оригинал. file внизу каждого поста в разделе «Ссылки» — их можно скачать на потом и открыть с помощью любимого web-браузер или PDF viewнапример, Adobe Acrobat.
Некоторые из наших крупнейших собраний документов / инструкций включают:
- Телефоны
- Яблоко
- Samsung
- Техника
- Пылесосы Bissell
- Термостаты Honeywell
- Homedics
- Эмблема
- Устройства Bluetooth
- Колонки JBL
- Колонки и умные устройства Anko
- Наушники и колонки Impirii Bluetooth
Если у вас есть руководство пользователя, которое вы хотели бы добавить на сайт, прокомментируйте ссылку!
Используйте поиск внизу страницы, чтобы найти свое устройство. Вы также можете найти дополнительные ресурсы на Поисковая система UserManual.wiki.
Время на прочтение
4 мин
Количество просмотров 28K
Всем привет. Наверное, любой разработчик на вопрос, что вам больше всего не нравится в процессе разработки, ответит: «написание документации» или упомянет об этом в самом начале списка проблем. В документировании действительно ничего интересного нет, но, тем не менее, руководство пользователя, как я уже писал в своем первом посте на Хабре, является важным компонентом любого профессионального продукта. Плохо составленная документация будет не только препятствием на пути привлечения новых покупателей, но и является большим минусом к имиджу продукта и разработчика.
В то же время, программу с хорошей справочной системой почти наверняка купят. Несмотря на распространенное мнение о том, что руководство пользователя никто не читает, жизнь показывает обратное. Если пользователь купил многофункциональную программу, с которой никогда до этого не работал, то справка пользователя станет его настольной книгой, к которой он будет обращаться, чтобы быстрее освоить возможности программы и найти ответы на вопросы, возникающие при эксплуатации программы. Поэтому понятная, последовательная и лаконичная справка пользователя – это всегда большой плюс к положительному имиджу продукта и его потенциалу для получения прибыли.
Сам иногда занимаюсь help-файлами и не понаслышке знаю, что создание справочной системы занимает время и является кропотливой и нудной работой, особенно документирование интерфейса. Однако пару месяцев назад открыл для себя инструмент, который значительно ускоряет этот процесс. Речь идет о программе Dr.Explain от самарской компании Индиго Байт Системз. Она мне понравилась продуманным интерфейсом и возможностью документировать интерфейс ПО в полуавтоматическом режиме.
Dr.Explain vs. Help and Manual
Итак, Dr.Explain позволяет создавать help-файлы в формате CHM для поставки вместе с приложением, справочные системы в HTML для размещения на сайте продукта, а также руководства пользователя в RTF и в PDF с оглавлениями и ссылками. Справочная система генерируется в разных форматах из единого источника, что позволяет быстро обновлять документацию при выходе новых версий ПО. В этом плане Dr.Explain ничем не отличается от Help and Manual, которой я давно пользуюсь.
Интерфейс состоит из двух областей. Первая – это панель навигации с древовидной структурой содержания проекта. А вторая – редактор страниц.
В дереве задается вся структура help-файла, включая заголовки папок и страниц. Редактор страниц состоит из стандартных инструментов для написания и форматирования текста, а также имеются инструменты для вставки гиперссылок, картинок, таблиц и переменных. Все это есть и в Help and Manual, но панель инструментов в Dr.Explain скомпонована, на мой взгляд, более продуманно.
Сравним:
Рисунок 1. Панель инструментов Dr.Explain
Рисунок 2. Панель инструментов Help and Manual
Главная фишка Dr.Explain – это автоматизация самого трудоемкого процесса документирования – создание аннотаций пользовательского интерфейса. Да, вы правильно меня поняли. Больше не нужно делать снимки экрана самому, рисовать выноски и стрелки, вставлять все это хозяйство в проект вручную – программа сама сделает снимок любой части интерфейса по вашему выбору, проанализирует и найдет (сама!) все значимые элементы (кнопки, элементы управления, списки), вставит снимок в проект справки и автоматически расставит стрелки и пояснительные выноски к изображениям. Пользователю остается всего лишь ввести краткое пояснение к каждой выноске и все.
Кроме того, к выноскам можно добавить и более подробные пояснения. Для всех выносок программа автоматически сгенерирует симпатичную на вид табличку, которая будет размещаться ниже скриншота с выносками и может включать в себя все эти подробные пояснения.
Такое полуавтоматическое документирование интерфейса значительно ускоряет и облегчает создание справочной системы, т.к. разработчику остается всего лишь добавить свои описания в выноски. В Help and Manual я все это тоже могу сделать – правда, придется делать это вручную. Обычно я делаю снимки окон в Snagit, обрабатываю края снимка, добавляю тень, рисую стрелки. А для документирования элементов окна вручную создаю табличку, нарезаю снимки кнопок и контролов, обрабатываю их края и вставляю в проект, а затем пишу описания каждой выноски. На это тратится уйма времени и усилий.
Кое-что еще…
В Dr.Explain есть и другие полезные возможности, которых, к сожалению, нет в Help and Manual. Например, есть удобный режим просмотра проекта – одним кликом по соответствующей кнопке можно быстро посмотреть, как будет выглядеть справка в формате CHM или HTML после компиляции. Превью открывается прямо в окне редактора. Поверьте, это очень удобно. Однако нет PDF-превью – это минус. В Help and Manual чтобы посмотреть, как выглядит справка, нужно постоянно компилировать проект.
Также в программе есть возможность интегрировать контекстно-зависимую справку прямо в приложение (F1), управление деревом навигации, набор шаблонов оформления, поддержка CSS, возможность быстрого обновления документации при выходе новой версии программы путем замены иллюстраций, но с сохранением выносок, аннотаций, описаний; функция поиска и индексации в онлайн-справке без программирования (PHP, ASP) или баз данных на стороне сервера.
Резюме
Вот, пожалуй, и все основные моменты, о которых я хотел здесь рассказать. Краткий обзор Dr.Explain я хотел написать еще два месяца назад, когда впервые увидел программу, но потом отложил эту затею на неопределенное время. А недавно снова готовил справку пользователя в Help and Manual и еще раз убедился, что документировать интерфейс все же удобнее в Dr.Explain.