Написання інструкцій

Створення файлу інструкції

Щоб почати писати інструкцію, необхідно створити файл з розширенням .mdx. Вам потрібно створити цей файл всередині каталогу /content/docs/en, тепер це залежить від того, в якому розділі ви хочете вказати орієнтацію, щоб визначити, яку теку ви повинні вкласти після неї.

Припустимо, що я хочу зробити посібник із бази java і я б розмістив його в "/content/docs/en/guides/java-basics". Вам доведеться трохи пошукати, щоб дізнатися, де ви хочете його розмістити.

Передній план

Передній план - це метадані вашого посібника, він розказує нам як зображати вашу інструкцію. Це має бути в верхній частині файлу, який починається з --- і закінчується ---.

Ось приклад:

---
title: "Основи Java"
description: "Вивчіть основи програмування Java."
authors:
   - name: "Ваше Ім'я"
      url: "https://yourwebsite.com"
icon: YourIcon 
---

Як бачите, це досить зрозуміло, вам просто потрібно заповнити дані для вашого конкретного посібника. Якщо у вас немає URL, на який ви хочете пов'язати самостійно, просто не пишіть всього рядка. Крім того, розділ авторів є необов'язковим, тому, якщо ви не хочете його додавати, ви можете просто пропустити його, хоча ми рекомендуємо вам зробити це та вказати себе як автора.

Відступи на передньому плані важливі, тому переконайтеся, що вони як у прикладі.

Структура вмісту

Потрібно структурувати зміст свого керівництва чітким і організованим. Ось кілька порад про те, як це зробити:

• Вступ: Почніть з огляду теми та того, що може вивчити читач.
• Передумови: Перелічіть будь-які передумови або попередні знання, які читач повинен мати, перш ніж поглибитися до посібника.
• Покрокові інструкції: Розбивайте вміст у чіткі кроки. Використовуйте заголовки та підзаголовки для організації інформації.
• Приклади коду: Додайте фрагменти коду для ілюстрації ключових моментів. Обов'язково поясніть кожен приклад ретельно.
• Висновок: Підсумуйте основні тези та заохочуйте читача до подальшого вивчення або спроби того, що він дізнався.

Тепер, якщо ви пишете справді великий розділ, вам слід розділити його на кілька сторінок, щоб читачеві було легше засвоїти інформацію. Ніхто не хоче читати велику стіну тексту!

Коли ми пишемо інструкції, ми також повинні думати про те, як люди будуть споживати їх, і багато людей віддають перевагу стислому змісту, а не читати детально. Ось чому розділити інформацію на кілька сторінок, тому для читача вона виглядає як менша кількість інформації. Також розгляньте можливість використання маркованих списків, нумерованих списків та інших методів форматування, щоб зробити вміст легшим для читання.

Форматування

Ми використовуємо Markdown для форматування наших посібників. Ось кілька ключових моментів, які слід пам’ятати:

• Використання заголовків (#, ##, ###) для організації вмісту.
• Використовуйте марковані списки та нумеровані списки для ясності.
• Use code blocks (```) for code snippets.
• Використовуйте посилання для ознайомлення з іншими посібниками або зовнішніми ресурсами.

Це той самий тип форматування, який ви побачите на більшості вебсайтів з документацією, а також на платформах соціальних мереж, таких як Discord.

Посилання

Всі знають, що таке посилання. Однак, існує різниця між посиланням на зовнішній ресурс і посиланням на внутрішній.

Загалом, у Markdown вони пишуться так: [Ваш текст](Ваше посилання)

Зовнішні

Нічого пояснювати, просто https://example.com.

Внутрішні

Тут не можна використовувати звичайні посилання. Припустимо, ваше посилання на інший посібник — https://hytalemodding.dev/en/docs/quick-start. Ви не можете так писати, бо ви посилаєтеся не лише на сторінку, а й на мову, що неправильно. Замість цього введіть ./quick-start, що є правильним і посилається на сторінку мовою користувача.

Доступ до файлів

• Поточна тека: ./
• Тека вище: ../ стільки разів, наскільки ця тека вище в ієрархії.

Значки

Якщо ви хочете додати значок для своєї сторінки, вам слід скористатися Lucide.

1. Перейдіть на сайт та знайдіть значок, який вам подобається.
2. Після вибору значка натисніть на нього, а потім натисніть «See in action».
3. Далі натисніть кнопку «React», який ми використовуємо. Вам знадобиться лише текст у фігурних дужках у першому рядку.
4. Далі просто вставте icon: YourIcon у Frontmatter.

Виноска

Ви також можете зробити виноску, щоб виділити важливу інформацію або поради. Використовуйте наступний синтаксис:

<Callout>
Це виноска.
</Callout>

Ви можете змінити колір виклику додавши атрибут type. Наприклад:

<Callout type="info">
    Це інформаційна виноска.
</Callout>

Доступні типи: info, warning, error та success.

Рівні складності

Це типи виносок, вони необов'язкові та показують, наскільки складною може бути ваша сторінка. Існує 3 основні рівні складності.

Їх використання таке ж, як і у виносці, але ми б радили не змінювати заголовок. Усередині ви пишете, чому ваша сторінка класифікується як така, і що користувач повинен знати.

Висновок

От і все! Тепер ви майстер написання інструкцій. Просто пам’ятайте, що не думайте, що вам потрібно бути ідеальним у своїй мові, пишіть посібник так, як ви поясните тему комусь, і не соромтеся просити відгуків чи допомоги, якщо вам це потрібно.

Приємного письма!