Справочное руководство это

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 ➡

Previous

Next

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

Справочное руководство, опубликованное в 2008 году в качестве онлайн-преемника Руководства по справочникам, было выборочным справочником по лучшие печатные и интерактивные справочные источники. Редакционная группа библиотекарей-справочников и предметных экспертов отобрала и аннотировала около 16 000 статей, которые были организованы по темам. Это была база данных по подписке, опубликованная Американской библиотечной ассоциацией, и она постоянно обновлялась. Он был задуман как ресурс для библиотек при ответах на справочные вопросы, планировании библиотечных инструкций, определении предметов для покупки и обучении персонала.

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

Интернет-продукт был закрыт 31 марта 2016 г.

Содержание

• 1 История
• 2 Текущие разработки
• 3 Ссылки
• 4 Внешние ссылки

История

Руководство было написано в первом десятилетии двадцатого века Алисой Бертой Крегер, главой Библиотечной школы Университета Дрекселя в Филадельфии, Пенсильвания. Она разработала 104-страничный том, предназначенный для обучения студентов и специалистов библиотечного сообщества. Наполненная короткими статьями и указателями к другим публикациям для дальнейшего чтения, Крёгер использовала свою книгу, чтобы «систематизировать как принципы обучения справочному библиотечному делу, так и область компетенции справочного библиотечного дела» (Kieft, 331). Он также включал серию указателей, описывающих и оценивающих справочные публикации по различным темам, и предназначался для того, чтобы помочь начинающему библиотекарю узнать о наиболее полезных и надежных справочных источниках, доступных на рынке. Американская библиотечная ассоциация опубликовала ее книгу как «Руководство по изучению и использованию справочников: руководство для библиотекарей, учителей и студентов». Крегер выпустил два издания: одно в 1902 году, а второе в 1907 году.

После смерти Крегера в 1909 году Американская библиотечная ассоциация спросила Исадора Гилберта Маджа, главу справочника. отдел библиотеки в Колумбийском университете, чтобы взять на себя проект. Мадж положил начало тенденции в Колумбии, которая продлилась бы несколько десятилетий, заставляя своих справочных сотрудников «вести четыре жизни — редакторами, администраторами, составителями коллекций и передовыми справочными специалистами» (Плотник, 130). Большая часть работы над Руководством выполнялась наряду с обычными задачами справочной работы по составлению коллекции и оказанию помощи студентам и профессорам в их исследовательских запросах. За это время указатели справочных материалов расширились, и книга претерпела два изменения названия: Новое руководство по справочным книгам в 1923 году и Руководство по справочным книгам в 1929 году.

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

Когда Юджин П. Шихи занял должность руководителя справочной службы Колумбии в 1967 году, он взял на себя руководство. Проработав несколько лет помощником Винчелла, Шихи перенял ее стиль, процесс отбора и организацию как свой собственный. Он начал выпускать дополнения к Руководству с версиями в 1968, 1970 и 1972 годах. Дополнения расширили записи восьмого издания Уинчелла, добавив указатели недавно опубликованных или недавно обнаруженных материалов. Новое девятое издание, которое требовало от Шихи и двух его помощников обновления и исправления записей из издания Винчелла и добавления материалов из трех своих приложений, было наконец опубликовано в 1976 году. Это девятое издание было первой версией, включавшей списки ранних электронных баз данных. Шихи продолжал редактировать и публиковать приложения до тех пор, пока не вышел на пенсию в 1986 году.

Редакция 10-го издания и 11-го издания перешла к журналу Association of College and Research Libraries ‘Choice. Руководство перестало быть видением одинокого человека, оно превратилось во все более совместный проект по мере роста объема справочной литературы и привлечения участников из библиотек по всей стране.

Текущие разработки

Использование Руководства становилось все реже и реже, поскольку исследования в большей степени были направлены на электронные базы данных, такие как EBSCOhost и JSTOR. О проекте разработки 12-го издания Руководства в качестве онлайн-базы данных было объявлено в 2000 году под редакцией Роберта Х. Кифта, в то время библиотекаря Хаверфорд-колледжа (ныне библиотекаря колледжа в Западном колледже). Это онлайн-издание было опубликовано в 2009 году и постоянно не имеет даты. Он был первым, в котором были перечислены веб-сайты, и первым, выпущенным в электронной форме. Последним главным редактором Интернет-справочника была Дениз Бобьен Беннетт, технический библиотекарь в Марстонской научной библиотеке Флоридского университета.

Издательство ALA Publishing в сотрудничестве с редакционным советом справочника объявило, что в связи с «текущим бизнес-климат », онлайн-продукт« Справочник по справочникам »прекратил принимать дополнительные подписки и будет закрыт 31 марта 2016 года.

Ссылки

• Читам, Берта М.« Обзор книги »Руководство по справочным книгам »Под редакцией Юджина П. Шихи». Журнал школьной библиотеки. 33.7. (Март, 1987): 88.
• Галвин, Том. «Обзор справочника Юджина П. Шихи». Библиотечный журнал. (15 сентября 1968 г.): 89.
• Харрис, Роберт Р. «Путеводитель по справочникам (книжное обозрение)». Библиотечный журнал. 101.22. (15 декабря 1976 г.): 2560.
• Плотник, Ст.. «С 8-го места Уинчелла на 9-е место у Шихи». Американские библиотеки. 8.3. (Март 1977 г.): 129-133.
• Кифт, Роберт. «Когда справочники не являются книгами: новое издание руководства по справочникам». Справочные и пользовательские услуги ежеквартально. 41.4. (Июль, 2002): 330-335.
• Рубин, Ричард Э. Основы библиотечной и информационной науки. 2-е изд. Нью-Йорк: Нил-Шуман Паблишерс, Инк., 2004.
• Шихи, Юджин П. «Предисловие». Путеводитель по справочникам. 10-е изд. Эд. Юджин П. Шихи. Чикаго: Американская библиотечная ассоциация, 1986. ix-xi.
• Уошберн, Энн. «Путеводитель по справочникам (книжное обозрение)». Библиотечный журнал. 105.13. (1 июля 1980 г.): 1502.

Внешние ссылки

• «Справочник по домашней странице». Архивировано из оригинала 15 февраля 2015 года.

справочное руководство