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

Создание гайд файла

Чтобы начать писать гайд, необходимо создать файл с расширением .mdx. Вам нужно создать этот файл внутри папки /content/docs/ru, теперь это зависит от того, в каком разделе вы хотите сделать гайд, так что вы можете решить, какую папку вы должны положить его после этого.

Предположим, я хочу создать руководство по основам java, тогда я помещу его в /content/docs/ru/guides/java-basics. Вам придется немного поискать, чтобы понять, где именно вы хотите это разместить.

Frontmatter

Frontmatter — это метаданные вашего руководства; они сообщают нашему сайту, как отображать ваше руководство. Это должно быть в самом верху файла, который начинается с --- и заканчивается ---.

Вот пример:

---
title: "База Джавы"
description: "Научимся базовым принципам программировании на Джава."
authors:
    - name: "Ваше имя"
      url: "https://yourwebsite.com"
---

Как видите, здесь всё довольно очевидно: вам просто нужно заполнить данные для вашего конкретного руководства. Если у вас нет URL-адреса, на который вы хотели бы ссылаться, просто не пишите эту строку целиком. Кроме того, раздел authors (авторы) является необязательным. Если вы не хотите его добавлять, можете просто пропустить его, хотя мы рекомендуем указать себя как автора.

Отступы в Frontmatter важны, поэтому убедитесь, что они соответствуют примеру.

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

Вы должны структурировать содержание вашего руководства четко и организованно. Вот несколько советов, как это сделать:

• Введение: Начните с обзора темы и того, чему читатель сможет научиться.
• Требования: Перечислите все предварительные требования или базовые знания, которыми должен обладать читатель перед изучением руководства.
• Пошаговые инструкции: Разделите контент на четкие, действительные шаги. Используйте заголовки и подзаголовки для организации информации.
• Примеры кода: Включите фрагменты кода для иллюстрации ключевых моментов. Обязательно подробно объясняйте каждый пример.
• Заключение: Подведите итог основным моментам и побудите читателя изучать тему дальше или опробовать то, чему он научился.

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

При написании руководств мы также должны думать о том, как люди будут их потреблять: многие предпочитают бегло просматривать контент, а не вчитываться в детали. Поэтому лучше разбивать информацию на несколько страниц — так читателю будет казаться, что объем информации меньше. Также рассмотрите возможность использования маркированных, нумерованных списков и других приемов форматирования, чтобы сделать контент более удобным для беглого просмотра.

Форматирование

Мы используем Markdown для форматирования наших гайдов. Вот несколько ключевых моментов, о которых следует помнить:

• Используйте заголовки (#, ##, ###), чтобы упорядочить содержимое.
• Используйте маркированные и нумерованные списки для наглядности.
• Use code blocks (```) for code snippets.
• Используйте ссылки для упоминания других руководств или внешних ресурсов.

Это тот же тип форматирования, который вы видите на большинстве сайтов с документацией, а также на социальных платформах, таких как Discord.

Вы также можете использовать выноски (Callouts), чтобы выделить важную информацию или советы. Используйте следующий синтаксис:

<Callout>
    Сообщение с выноской.
</Callout>

Вы можете изменить цвет выноски (callout), добавив атрибут 'type'. Например:

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

Доступные типы: info, warning, error и success.

Заключение

Вот и все! Теперь вы --- гайд мастер. Главное помните, вам не нужно в совершенстве владеть английским, пишите руководство так, как объясняли бы тему кому-либо и не стесняйтесь просить обратную связь или помощь, если она вам понадобится.

Удачи в написании!