Інструкції з написання

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

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

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

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

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

Ось приклад:

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

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

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

Структура контенту

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

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

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

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

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

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

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

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

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

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

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

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

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

Висновок

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

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