Документация

Appearance

Туториал для авторов ​

Эта страница поможет быстро и единообразно писать клиентскую документацию.

1. Базовый шаблон документа ​

Используйте этот каркас как старт:

md
# Название документа

Коротко: что это, кому нужно, в каких случаях использовать.

## Что делает
- Пункт 1
- Пункт 2

## Как использовать
1. Шаг 1
2. Шаг 2
3. Шаг 3

## Пример
```bash
curl -X GET http://localhost:8787/api/health
```

## Частые ошибки
::: warning
Опишите проблему, причину и решение.
:::

2. Заголовки и структура ​

Правило: один документ = одна тема.

md
# H1 — название страницы
## H2 — крупные разделы
### H3 — подшаги внутри раздела

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

  • Не пропускайте уровни (## сразу после #, затем ###).
  • Делайте заголовки короткими и по делу.
  • Старайтесь, чтобы один раздел отвечал на один вопрос.

3. Текст и форматирование ​

md
Обычный текст
**Жирный**
*Курсив*
`инлайн-код`
~~устаревшее~~

Пример:

Чтобы запустить сервис, выполните npm run api:dev.

4. Списки и чеклисты ​

Маркированный список:

md
- Первый пункт
- Второй пункт
- Третий пункт

Нумерованный список:

md
1. Открыть админку
2. Создать документ
3. Нажать Publish

Чеклист:

md
- [x] Заголовок заполнен
- [x] Примеры команд проверены
- [ ] Ссылки перепроверены

5. Ссылки и изображения ​

Внешняя ссылка:

md
[Документация VitePress](https://vitepress.dev/)

Внутренняя ссылка:

md
[Туториал](/writing-tutorial)

Изображение:

md
![Скриншот результата](https://example.com/screenshot.png)

Вставка скриншота из буфера обмена ​

В редакторе админки можно вставлять изображение прямо через Ctrl+V.

Что происходит:

  1. Скриншот загружается на сервер.
  2. В Markdown автоматически вставляется строка:
md
![screenshot](http://localhost:8787/api/assets/<file-name>.png)

6. Кодовые блоки ​

Указывайте язык для подсветки:

md
```ts
const baseUrl = 'http://localhost:8787/api'
```

Пример для bash:

md
```bash
npm run api:dev
```

Пример JSON-ответа:

md
```json
{
  "ok": true
}
```

7. Таблицы ​

md
| Поле | Тип | Описание |
| --- | --- | --- |
| title | string | Название документа |
| slug | string | URL-ключ |
| markdown | string | Содержимое в Markdown |

8. Полезные блоки VitePress ​

md
::: info
Нейтральная информация.
:::

::: tip
Практическая подсказка.
:::

::: warning
Важно учесть перед запуском.
:::

::: danger
Критичный риск или необратимое действие.
:::

::: details
Скрытый блок с деталями.
:::

Примеры:

INFO

Документы для клиентов должны описывать только опубликованное поведение.

TIP

Сначала пишите «что сделать», потом «почему».

WARNING

Перед публикацией проверяйте команды на чистом окружении.

Details

Пример скрытого блока с деталями.

9. Акценты и предупреждения в тексте ​

Плохо:

md
Система иногда может работать не так.

Хорошо:

md
::: warning
Если API недоступен, проверьте, что запущен `npm run api:dev` на `http://localhost:8787`.
:::

10. Примеры «плохо / хорошо» ​

Нечетко:

md
Нажмите кнопку и дождитесь.

Четко:

md
Нажмите **Publish**. После публикации ссылка автоматически копируется в буфер обмена.

Неполный пример:

md
Сделайте запрос к API.

Полный пример:

md
```bash
curl -X GET http://localhost:8787/health
```
Ожидаемый ответ:
```json
{ "ok": true }
```

11. Готовые шаблоны под задачи ​

Шаблон: Инструкция ​

md
# Как выполнить действие

## Условия
- Что должно быть подготовлено

## Шаги
1. ...
2. ...
3. ...

## Результат
Что пользователь должен увидеть.

Шаблон: Описание API ​

md
# Метод API

## Endpoint
`POST /api/example`

## Тело запроса
```json
{ "name": "value" }
```

## Ответ
```json
{ "ok": true }
```

## Ошибки
| Код | Причина |
| --- | --- |
| 400 | Некорректный запрос |
| 401 | Не авторизован |

Шаблон: Разбор проблемы ​

md
# Проблема: ...

## Симптомы
- ...

## Причина
- ...

## Решение
1. ...
2. ...

## Проверка
Как убедиться, что проблема устранена.

12. Чеклист перед публикацией ​

  • Название документа отражает суть.
  • Есть шаги и ожидаемый результат.
  • Все команды и URL проверены.
  • Нет «TODO», «потом добавить», «пример позже».
  • Ссылки и изображения открываются.
  • Орфография и формулировки проверены.

13. Минимальный стандарт качества ​

Документ считается готовым, если:

  1. По нему можно выполнить задачу без устных пояснений.
  2. Указаны входные условия и ожидаемый результат.
  3. Ошибки и ограничения описаны явно.
  4. Есть хотя бы один рабочий пример.