Правила оформления документации в GitHub Wiki - ixray-team/ixray-1.6-stcop GitHub Wiki

Правила оформления документации в GitHub Wiki

Структура документации

1. Заголовок и мета-информация

Недопустимые символы в название статьи: ?, *, <, >, `:

# Название страницы

> [!IMPORTANT]  
> **Статус**: [Поддерживается/Устарело/В разработке]  
> **Минимальная версия**: [Версия продукта]  
> **Последнее обновление**: [YYYY-MM-DD]

2. Обзор

Краткое описание функционала/возможности:

## Обзор

[1-3 абзаца с объяснением ключевой концепции]  
[Пример использования в одном предложении]

3. Синтаксис и использование

3.1 Базовый синтаксис

## Синтаксис

[Четкое описание формата]  
[Минимальный рабочий пример]

3.2 Расширенные возможности

Писать при наличии

4. Примеры использования

Примеры

Сценарий 1: [Название]

[код примера]

→ [Пояснение результата]

Сценарий 2: [Название]

[код примера]

→ [Пояснение результата]

5. Рекомендации и ограничения

Рекомендации

  • Правильное использование:
    [Советы по применению]
  • Ограничения:
    [Потенциальные проблемы и их решения]
  • Анти-паттерны:
    [Типичные ошибки]

6. Связанные разделы

См. также


Дополнение к правилам оформления

1. Форматирование кода

  • Используйте блоки кода с указанием языка:
    #include "file.ltx"
  • Для inline-кода: `внутри строки`

2. Визуальные акценты

  • Важные заметки:
    > [!NOTE]  
    > Пояснительный текст
  • Предупреждения:
    > [!WARNING]  
    > Текст предупреждения

3. Ссылки и перекрестные ссылки

  • Внутри Wiki:
    [текст ссылки](Имя-страницы)
  • На внешние ресурсы:
    [текст](https://example.com)

4. Изображения и диаграммы

![Описание изображения](https://example.com/image.png)

Проверка перед публикацией

  1. Проверьте работоспособность всех примеров кода
  2. Убедитесь, что ссылки ведут на актуальные страницы
  3. Проверьте грамматику и читаемость текста
⚠️ **GitHub.com Fallback** ⚠️