User Documentation В этом учебнике вы узнаете, как создать учебник.
Учебник — это урок, который проводит вас через серию практических шагов. Он предлагает опыт обучения через выполнение каких-либо действий. Это лучший способ познакомиться с темой, которая вам ещё не знакома. Учебники играют решающую роль в любой документации: они знакомят новичков с системой, направляют их первые шаги, служат витриной и дают приятный и лёгкий опыт знакомства с темой. Один из "секретов" достижения этого — оставить за рамками всё, что может отвлечь в процессе обучения. Например:
- Альтернативные способы сделать что-то или способы выполнить что-то очень специфическое.
- Полные справочники по всем настройкам и техническое описание их структуры.
- Подробные объяснения и исторический контекст.
Эту дополнительную информацию лучше всего предоставлять отдельно. Старайтесь не смешивать её с основным материалом, так как это только затуманит учебник. Это основной принцип фреймворка Diátaxis — систематического подхода к улучшению документации. Поместите упомянутую выше дополнительную информацию в соответствующие практические руководства, справочники и объяснения. В практических руководствах вы можете быстро найти, как выполнить что-то конкретное. В справочниках вы можете посмотреть, как всё устроено, какие у этого настройки и где найти дополнительную информацию. С помощью объяснений вы можете углубить своё понимание темы.
Хотя учебник предлагает знакомство с темой, он не предназначен исключительно для начинающих. Он также может быть введением в сложную тему! Чётко обозначьте в начале вашего учебника, какие знания или навыки необходимы для его выполнения.
Если вы учите кого-то готовить, вам нужно объяснить такие вещи, как техники нарезки, как пользоваться духовкой и другие базовые кухонные навыки. Вы начинаете с простого рецепта, желательно такого, который легко даёт хороший конечный результат. Сам этот результат не является главной целью: вы хотите научить определённым навыкам. Именно это и делает учебник. Тому, кто умеет готовить и хочет приготовить что-то конкретное, такой учебник не нужен — ему нужен рецепт. Рецепты — это практические руководства по кулинарии.
Пошаговая инструкция
Чтобы создать учебник:
- Соберите информацию по теме. Существующая документация, видео и т. д. Отметьте моменты, которые показались вам запутанными или заняли время на понимание. Есть ли вопросы по этой теме на форуме?
- Какие понятия задействованы? Небольшая схема может помочь. Не пытайтесь охватить всё полностью, но чётко обозначьте, что важно для данного учебника, а что нет.
- Требуются ли какие-либо специфические знания или навыки, которым нужно обучить в вашем учебнике?
- Создайте пример, в котором можно использовать все понятия и навыки, которые вы хотите донести в учебнике. Сделайте пример максимально простым.
- Определите и опишите шаги, ведущие к конечному результату. Каждый шаг должен быть воспроизводим вашим читателем.
- Исключите все объяснения, справочники, альтернативы и особые случаи; вынесите их в отдельные материалы.
- Напишите введение. Чему вы научитесь в этом учебнике? Укажите необходимые предварительные условия для выполнения учебника.
- Напишите заключение. Чему мы научились? Можно также указать следующие шаги для дальнейшего изучения.
- Добавьте скриншоты с пометками, иллюстрирующими необходимые действия. Совет: используйте номера на скриншоте и давайте пояснения в тексте. Это облегчает повторное использование скриншота в переводах и минимизирует усилия по созданию скриншотов для разных языков.
- Добавьте схемы для объяснения структур, связей и процессов.
- Добавьте сопутствующие материалы с объяснениями, справочниками и практическими руководствами.
- Поместите все материалы по одной теме под обзорным материалом, объясняющим, что есть что, как они связаны и с чего начать.
Пример: создание и публикация материала в Joomla
В качестве примера давайте создадим учебник о том, как создать и опубликовать материал под пунктом меню в Joomla.
Сбор информации
В нашем руководстве пользователя вы найдёте соответствующие материалы в разделах «Начало работы», «Материалы» и «Меню». Часто возникает путаница при начале работы с Joomla: после создания материала он не отображается, даже если он отмечен как «опубликован». Чтобы материал был виден, на него должна вести ссылка. Существует несколько способов создать такую ссылку (например, пункт меню, макет категории-блога, размещение на главной странице блога путём отметки материала как избранного или ссылка из другого материала), но сейчас мы сосредоточимся на том, чтобы сделать материал доступным через пункт меню.
Понятия и навыки
У нас есть «контент», «материал», «меню» и «пункт меню». Нужно прояснить эти термины. Мы покажем, где найти эти элементы в меню панели управления. В этом учебнике мы не рассматриваем «категории» или «избранное».
Предварительные требования
У вас должен быть доступ к панели управления работающего сайта Joomla и вы должны знать, как войти в систему.
Цель
Наша цель — научиться создавать новый материал Joomla и новый пункт меню, под которым мы разместим наш материал.
Шаги
Выполните следующие шаги для достижения нашей цели:
A. Создание материала
- Войдите в панель управления Joomla.
- Сначала мы создадим материал. Перейдите в меню «Контент» слева и выберите «Материалы».
- Нажмите «Создать», чтобы создать новый материал.
- Введите заголовок и содержимое вашего материала.
- Нажмите «Сохранить и закрыть», чтобы сохранить материал.
B. Создание пункта меню, ссылающегося на материал
Чтобы отобразить материал на сайте, мы создадим пункт меню, ссылающийся на материал. Перейдите в меню «Меню» слева и выберите «Главное меню».
- Как и с материалом, нажмите «Создать», чтобы создать новый пункт меню.
- Введите заголовок для вашего пункта меню. Это заголовок, который будет отображаться в меню. Он не обязательно должен совпадать с заголовком материала. Обычно он короче заголовка материала, чтобы лучше вписываться в меню.
- Выберите тип пункта меню: в разделе «Материалы» выберите «Один материал».
- Выберите материал: выберите только что созданный материал.
- Перейдите на сайт и обновите страницу. Поздравляем: теперь вы можете щёлкнуть по пункту меню, чтобы увидеть свой материал.
Введение
Напишите введение: чему вы научитесь в этом учебнике и какие предварительные требования необходимы.
Отфильтруйте дополнительную информацию
Можно ли что-то опустить из написанного до сих пор? Например, на шаге 2 создания пункта меню я упомянул, что заголовок пункта меню не обязательно должен совпадать с заголовком материала. Является ли это необходимым дополнением к данному учебнику? Если нет, то лучше пока это опустить. Но это даёт намёк на более специализированный материал о заголовках материалов и пунктов меню и о том, когда они отображаются, с учётом общих настроек материалов, индивидуальных настроек материала на вкладке «Настройки», настроек пункта меню на вкладке «Настройки» и прочего. Также было бы неплохо сделать справочный материал о том, как материалы, категории и пункты меню работают вместе; в таком материале старайтесь быть исчерпывающим, перечислив все возможности. Специализированным практическим руководством могло бы стать: «Как отобразить заголовок материала?», показывающее настройки в общих параметрах материалов, а также в индивидуальных настройках материала и пункта меню. Материал-объяснение мог бы рассказать о предпосылках того, почему Joomla использует термин «материал», в то время как, например, WordPress использует термин «запись», или о том, как материал отображается на итоговой странице.
Заключение
Подведите итог всему в кратком резюме. И укажите возможные следующие шаги для дальнейшего изучения (например, учебник о добавлении категории или практическое руководство о быстром сохранении в меню).
Изображения и графика
Сделайте скриншоты, показывающие кнопки и поля, задействованные при создании материала и пункта меню. Отметьте задействованные кнопки и поля.
Для ясности вы можете добавить диаграмму, показывающую, как материал размещается «под» пунктом меню.
Добавьте справочники, практические руководства и объяснения
Разместите всю дополнительную информацию и инструкции в отдельных материалах.
Обзор
Если у вас несколько материалов по одной теме, вам следует создать обзорный материал, объясняющий, как материалы связаны между собой и с чего начать.
Упражнение
Начните создавать описанный выше учебник о том, как создать и опубликовать материал в Joomla. Лучший способ научиться — это делать самому. Мы опубликуем пример того, как это может выглядеть, в текущем руководстве пользователя на этом сайте. Но мы с радостью разместим здесь вашу версию, если вы сможете улучшить текущую.
(эта статья также была опубликована в Joomla Community Magazine за февраль 2025 года)