Лучшие практики

Освоив синтаксис Markdown, как писать качественную и поддерживаемую техническую документацию? Это руководство содержит лучшие практики — от базовых стандартов до продвинутых советов.

Проектирование структуры документа

Организация каталогов

project/
├── README.md                 # Обзор проекта
├── docs/
│   ├── index.md              # Главная страница документации
│   ├── getting-started/
│   │   ├── installation.md   # Руководство по установке
│   │   ├── quick-start.md    # Быстрый старт
│   │   └── examples.md       # Примеры кода
│   ├── api/
│   │   ├── overview.md       # Обзор API
│   │   ├── authentication.md # Аутентификация
│   │   └── endpoints/        # Конечные точки API
│   ├── guides/
│   │   ├── best-practices.md # Лучшие практики
│   │   └── troubleshooting.md# Устранение неполадок
│   └── changelog.md          # История изменений
└── assets/
    └── images/               # Графические материалы

Иерархия содержания

# Заголовок 1 уровня — Тема документа

Кратко опишите содержание и цели документа.

## Заголовок 2 уровня — Основные разделы

### Заголовок 3 уровня — Конкретные темы

Детальное содержание и пояснения...

#### Заголовок 4 уровня — Подразделы

Детали реализации...

##### Заголовок 5 уровня — Дополнительные замечания

Важные советы и примечания...

> **Примечание**: Не используйте более пяти уровней заголовков, чтобы не усложнять структуру.

Стандарты написания контента

Языковой стиль

✅ Рекомендуется:

1. **Используйте лаконичный и понятный язык**
   - Избегайте длинных предложений
   - Используйте активный залог
   - Минимизируйте жаргон

2. **Соблюдайте единый тон**
   - Официальный, но дружелюбный
   - Ориентируйтесь на пользователя
   - Избегайте чрезмерно технических формулировок

3. **Давайте конкретные рекомендации**
   - Используйте точные числа и примеры
   - Приводите чёткие шаги
   - Указывайте ожидаемые результаты

❌ Избегайте:

- Неясных формулировок
- Чрезмерного пассивного залога
- Отсутствия необходимого контекста
- Предположений о знаниях читателя

Абзацы и форматирование

<!-- ✅ Хорошая структура абзаца -->
## Установка Node.js

Для работы с нашим инструментом сначала установите Node.js. Node.js — это среда выполнения JavaScript на сервере.

### Системные требования

Перед установкой убедитесь, что ваша система соответствует требованиям:

- ОС: Windows 10+, macOS 10.12+ или Linux
- Оперативная память: не менее 4 ГБ
- Свободное место: не менее 1 ГБ

### Шаги установки

1. Перейдите на [официальный сайт Node.js](https://nodejs.org/)
2. Скачайте установщик для вашей ОС
3. Запустите установщик и следуйте инструкциям
4. Откройте терминал и проверьте установку:

Если отображается номер версии — установка прошла успешно.

Установите nodejs, скачайте с официального сайта, затем установите и проверьте версию для подтверждения успеха


## Стандарты примеров кода

### Лучшие практики для блоков кода

Создание пользователя

Пример использования API для создания нового пользователя:

javascript

// Импорт необходимых библиотек
const axios = require('axios');

// Настройка конечной точки API
const API_BASE_URL = 'https://api.example.com';
const API_KEY = 'your-api-key';

// Функция создания пользователя
async function createUser(userData) {
  try {
    const response = await axios.post(`${API_BASE_URL}/users`, userData, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Пользователь создан:', response.data);
    return response.data;
  } catch (error) {
    console.error('Ошибка создания пользователя:', error.response.data);
    throw error;
  }
}

// Пример использования
const newUser = {
  name: 'Zhang San',
  email: 'zhangsan@example.com',
  role: 'user'
};

createUser(newUser);

Ожидаемый результат:

json

{
  "id": "12345",
  "name": "Zhang San",
  "email": "zhangsan@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

Важные советы:

Замените your-api-key на ваш реальный ключ
Проверьте сетевое соединение
Храните ключ в безопасности, не добавляйте его в систему контроля версий

javascript

// Создать пользователя
axios.post('/users', data)

Этот код создаёт пользователя.


### Примеры командной строки

Развёртывание проекта

1. Сборка проекта

bash

# Установить зависимости
npm install

# Запустить тесты
npm test

# Собрать production-версию
npm run build

2. Развёртывание на сервере

bash

# Подключиться к серверу
ssh user@server.example.com

# Перейти в каталог проекта
cd /var/www/myproject

# Получить последний код
git pull origin main

# Перезапустить сервис
sudo systemctl restart myproject

3. Проверка развёртывания

bash

# Проверить статус сервиса
sudo systemctl status myproject

# Просмотреть логи
sudo journalctl -u myproject -f

Ожидаемые результаты:

Статус сервиса: active (running)
При переходе на https://yoursite.com отображается последняя версия


## Управление ссылками и справками

### Внутренние ссылки

Для подробной инструкции по установке см. Руководство по установке.

Для аутентификации API см. Документация по аутентификации.


Если вы столкнулись с проблемами, обратитесь к [руководству по устранению неполадок](./index.md#common-issues).

<!-- ❌ Избегайте -->
Нажмите [сюда](./index.md) для установки.
См.: ./index.md

Внешние ссылки

<!-- ✅ Давайте контекст и пояснения -->
Наш API построен на [архитектуре REST](https://restfulapi.net/),
следует [стандартам HTTP-статусов](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).

Подробнее о JWT см. в
[официальной документации JWT](https://jwt.io/introduction/) и
[спецификации RFC 7519](https://tools.ietf.org/html/rfc7519).

<!-- ✅ Добавляйте иконки для внешних ссылок -->
- [GitHub Repo](https://github.com/example/project) 🔗
- [Демо](https://demo.example.com) 🌐
- [Официальная документация](https://docs.example.com) 📚

Справочные ссылки

<!-- ✅ Используйте справочные ссылки для чистоты -->
Мы поддерживаем несколько [методов аутентификации][auth-methods], включая
[API-ключи][api-keys], [OAuth 2.0][oauth] и [JWT][jwt].

Для подробной настройки см. [Руководство по конфигурации][config-guide],
для часто задаваемых вопросов — [страницу FAQ][faq].

<!-- Ссылки определяются в конце -->
[auth-methods]: ./index.md
[api-keys]: ./index.md#api-keys
[oauth]: ./index.md#oauth-20
[jwt]: ./index.md#jwt
[config-guide]: ./index.md
[faq]: /index.md.md

Оптимизация изображений и медиа

Организация и именование изображений

<!-- ✅ Осмысленные имена файлов -->
assets/
├── images/
│   ├── ui/
│   │   ├── dashboard-overview.png
│   │   ├── user-profile-edit.png
│   │   └── settings-general.png
│   ├── diagrams/
│   │   ├── system-architecture.svg
│   │   ├── data-flow-diagram.png
│   │   └── user-workflow.png
│   └── screenshots/
│       ├── installation-step-1.png
│       ├── installation-step-2.png
│       └── installation-complete.png

<!-- ❌ Избегайте -->
assets/
├── images/
│   ├── img1.png
│   ├── pic2.jpg
│   ├── screenshot.png
│   └── diagram.svg

Принципы проектирования таблиц

Таблицы данных

<!-- ✅ Чёткая структура таблицы -->
### Список API-эндпоинтов

| Метод | Endpoint | Описание | Auth | Параметры |
|-------|----------|----------|------|-----------|
| GET    | `/api/users`        | Получить список пользователей | ✅   | `page`, `limit`, `sort` |
| POST   | `/api/users`        | Создать нового пользователя   | ✅   | `name`, `email`, `role` |
| GET    | `/api/users/{id}`   | Получить пользователя         | ✅   | `id` (path param) |
| PUT    | `/api/users/{id}`   | Обновить пользователя         | ✅   | `id`, `name`, `email` |
| DELETE | `/api/users/{id}`   | Удалить пользователя          | ✅   | `id` (path param) |

**Примечания:**
- ✅ — требуется аутентификация
- Все эндпоинты требуют действительный API-ключ в заголовке запроса
- Параметры пути указываются прямо в URL
- Query-параметры передаются как `?key=value&key2=value2`

<!-- ✅ Таблица сравнения -->
### Сравнение тарифных планов

| Функция      | Бесплатно | Pro      | Enterprise |
|--------------|-----------|----------|------------|
| Пользователи | До 5      | До 50    | Неограниченно |
| Хранилище    | 1ГБ       | 100ГБ    | 1ТБ        |
| API-вызовы   | 1 000/мес | 10 000/мес| Неограниченно |
| Поддержка    | Сообщество| Email    | 24/7 персонально |
| Цена         | Бесплатно | ¥99/мес  | ¥999/мес   |

[Обновить сейчас](https://www.markdownlang.com/pricing) | [Связаться с отделом продаж](mailto:sales@example.com)

Сложные данные

<!-- ✅ Используйте HTML-таблицы для сложных данных -->
### Требования к серверу

<table>
  <thead>
    <tr>
      <th rowspan="2">Параметр сервера</th>
      <th colspan="3">Рекомендуемая конфигурация</th>
    </tr>
    <tr>
      <th>Малое развёртывание<br>(&lt;1K пользователей)</th>
      <th>Среднее развёртывание<br>(1K-10K пользователей)</th>
      <th>Крупное развёртывание<br>(&gt;10K пользователей)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>CPU</strong></td>
      <td>2 ядра</td>
      <td>4 ядра</td>
      <td>8+ ядер</td>
    </tr>
    <tr>
      <td><strong>Память</strong></td>
      <td>4ГБ</td>
      <td>8ГБ</td>
      <td>16ГБ+</td>
    </tr>
    <tr>
      <td><strong>Хранилище</strong></td>
      <td>50ГБ SSD</td>
      <td>200ГБ SSD</td>
      <td>500ГБ+ SSD</td>
    </tr>
    <tr>
      <td><strong>Сеть</strong></td>
      <td>100Мбит/с</td>
      <td>1Гбит/с</td>
      <td>10Гбит/с</td>
    </tr>
  </tbody>
</table>

Контроль версий и совместная работа

Управление версиями документа

<!-- ✅ Добавляйте информацию о версии в начале -->
---
title: Руководство пользователя API
version: 2.1.0
last_updated: 2024-01-15
author: Technical Docs Team
---

# Руководство пользователя API

> **Примечание о версии**: Этот документ относится к API v2.1.0 и выше.
> Для старых версий см. [архивную документацию](./archive/).

## История изменений

### v2.1.0 (2024-01-15)
- Добавлено управление группами пользователей
- Улучшена аутентификация
- Исправлены известные ошибки

### v2.0.0 (2024-01-01)
- Рефакторинг архитектуры API
- Обновлена аутентификация
- Добавлены пакетные операции

Стандарты коммитов в Git

<!-- ✅ Стандартный формат сообщений коммита -->
docs: Обновить документацию по аутентификации API

- Добавлен пример OAuth 2.0
- Исправлены ошибки в примерах кода
- Обновлены связанные ссылки

closes #123

<!-- ✅ Объяснения типов коммитов -->
Префиксы типов:
- docs: Обновление документации
- feat: Новая функциональность
- fix: Исправление ошибок
- style: Изменения форматирования
- refactor: Рефакторинг структуры
- test: Добавление тестов
- chore: Обновления сборки или инструментов

Стандарты совместной работы над документацией

<!-- Руководство по вкладу -->
## Руководство по вкладу

### Процесс отправки

1. **Сделайте fork репозитория** — создайте свою копию
2. **Создайте ветку** — для ваших изменений
   ```bash
   git checkout -b docs/update-api-guide

Пишите контент — следуйте стандартам
Тестируйте локально — убедитесь, что документация отображается корректно
Делайте коммиты — используйте стандартные сообщения
Создайте PR — подробно опишите изменения

Чек-лист ревью

[ ] Точность содержания
[ ] Ясность языка
[ ] Соответствие форматированию
[ ] Валидность ссылок
[ ] Примеры кода работают
[ ] Изображения отображаются


## Доступность и интернационализация

### Дизайн с учётом доступности

<!-- ✅ Дизайн документации с учётом доступности -->
### Цвет и контраст

Используя цвет для передачи информации, добавляйте и другие подсказки:

::: tip Успех
✅ Успех: Операция выполнена
:::

::: danger Ошибка
❌ Ошибка: Операция не выполнена
:::

### Альтернативный текст

Давайте осмысленный alt-текст для всех изображений:

![Схема архитектуры системы: поток данных между клиентом, API-шлюзом, микросервисами и БД](/assets/images/main-interface.png)

### Навигация с клавиатуры

Структура документа должна поддерживать навигацию с клавиатуры:

- Логическая иерархия заголовков
- Ссылки оглавления
- Важные ссылки легко найти

### Интернационализация

project/ ├── docs/ │ ├── en/ # Английская документация │ │ ├── README.md │ │ └── api/ │ ├── zh/ # Документация на китайском │ │ ├── README.md │ │ └── api/ │ └── ja/ # Документация на японском │ ├── README.md │ └── api/

Языковые версии

Последнее обновление: 15 января 2024 (en-US) 最后更新时间：2024年1月15日 (zh-CN) 最終更新日：2024年1月15日 (ja-JP)


## Оптимизация производительности

### Оптимизация загрузки документа

Сложная схема системы

<!-- ✅ Разделение длинных документов -->
### Разделение длинных документов

Делите длинные документы на части:

1. [Обзор](./overview.md) — базовые понятия
2. [Быстрый старт](./quickstart.md) — 5 минут на запуск
3. [Учебник](./tutorial.md) — полный курс
4. [API-справочник](./api-reference.md) — вся документация по API
5. [Примеры](./examples.md) — реальные кейсы

🔍 Показать расширенные параметры конфигурации

Расширенная конфигурация

yaml

# Пример подробной конфигурации
server:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem

Эти параметры для тонкой настройки production-среды...

Оптимизация для поисковых систем

<!-- ✅ SEO для документации -->
---
title: "Руководство по аутентификации API — Полное решение для идентификации"
description: "Узнайте, как использовать OAuth 2.0, JWT и API-ключи для безопасной аутентификации. Примеры кода и лучшие практики."
keywords: ["API authentication", "OAuth", "JWT", "security", "identity"]
---

# Руководство по аутентификации API

Узнайте, как безопасно аутентифицировать и авторизовать API-запросы...

## В этой главе

В этом руководстве рассматриваются следующие методы аутентификации:

1. [Аутентификация по API-ключу](#api-key-authentication) — просто и быстро
2. [OAuth 2.0](#oauth-20) — отраслевой стандарт
3. [JWT-токены](#jwt-tokens) — статeless-аутентификация

Контроль качества

Чек-лист проверки содержания

<!-- 📋 Чек-лист качества документации -->
## Чек-лист перед публикацией

### Качество содержания
- [ ] Информация точна и полна
- [ ] Язык ясен
- [ ] Логичная структура
- [ ] Примеры кода работают
- [ ] Скриншоты актуальны

### Техническая проверка
- [ ] Валидность ссылок
- [ ] Подсветка кода
- [ ] Изображения отображаются
- [ ] Форматирование таблиц
- [ ] Формулы отображаются

### Пользовательский опыт
- [ ] Навигация понятна
- [ ] Поиск работает
- [ ] Адаптация под мобильные
- [ ] Скорость загрузки
- [ ] Доступность

### Поддержка
- [ ] Обновлена информация о версии
- [ ] История изменений записана
- [ ] Связанные документы синхронизированы
- [ ] Устаревшие функции отмечены
- [ ] Есть гайды по миграции

Сбор обратной связи

<!-- ✅ Механизм сбора обратной связи -->
## Помогите нам стать лучше

### Обратная связь по документации

Если вы нашли ошибку или у вас есть предложения:

1. **Быстрая обратная связь**: [Оставьте issue](https://github.com/example/docs/issues/new?template=doc-feedback.md)
2. **Детальное обсуждение**: [Присоединяйтесь к обсуждению](https://github.com/example/docs/discussions)
3. **Редактируйте напрямую**: [Изменить эту страницу](https://github.com/example/docs/edit/main/docs/api/authentication.md)

### Оцените страницу

Была ли эта страница полезна?

👍 Да | 👎 Требует доработки | 💡 Предложение

### Контакты

- 📧 Команда документации: docs@example.com
- 💬 Техподдержка: support@example.com
- 🐦 Twitter: [@ExampleDocs](https://twitter.com/ExampleDocs)

Связанный синтаксис

Встраивание HTML — расширения HTML
Математические формулы — выражения LaTeX
Диаграммы — построение графиков
Инструменты и плагины — рекомендуемые инструменты

Инструменты и ресурсы

Инструменты для качества документации

textlint: Проверка стиля и орфографии
markdownlint: Проверка синтаксиса Markdown
alex: Проверка инклюзивности языка
Hemingway Editor: Анализ читаемости

Платформы для совместной работы

GitBook: Совместная работа над документацией
Notion: Многофункциональные заметки и база знаний
Confluence: Корпоративная документация
Slab: Современные командные документы

Инструменты аналитики

Google Analytics: Аналитика посещаемости
Hotjar: Анализ поведения пользователей
Mixpanel: Отслеживание взаимодействий
FullStory: Полная запись сессий пользователей

Инструменты автоматизации

GitHub Actions: Сборка и деплой документации
Zapier: Автоматизация рабочих процессов
IFTTT: Простые правила автоматизации
n8n: Open-source автоматизация

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

Лучшие практики ​

Проектирование структуры документа ​

Организация каталогов ​

Иерархия содержания ​

Стандарты написания контента ​

Языковой стиль ​

Абзацы и форматирование ​

Установите nodejs, скачайте с официального сайта, затем установите и проверьте версию для подтверждения успеха ​

Создание пользователя ​

Развёртывание проекта ​

1. Сборка проекта ​

2. Развёртывание на сервере ​

3. Проверка развёртывания ​

Внешние ссылки ​

Справочные ссылки ​

Оптимизация изображений и медиа ​

Рекомендации по использованию изображений ​

Организация и именование изображений ​

Принципы проектирования таблиц ​

Таблицы данных ​

Сложные данные ​

Контроль версий и совместная работа ​

Управление версиями документа ​

Стандарты коммитов в Git ​

Стандарты совместной работы над документацией ​

Чек-лист ревью ​

Языковые версии ​

Расширенная конфигурация ​

Оптимизация для поисковых систем ​

Контроль качества ​

Чек-лист проверки содержания ​

Сбор обратной связи ​

Связанный синтаксис ​

Инструменты и ресурсы ​

Инструменты для качества документации ​

Платформы для совместной работы ​

Инструменты аналитики ​

Инструменты автоматизации ​

Лучшие практики

Проектирование структуры документа

Организация каталогов

Иерархия содержания

Стандарты написания контента

Языковой стиль

Абзацы и форматирование

Установите nodejs, скачайте с официального сайта, затем установите и проверьте версию для подтверждения успеха

Создание пользователя

Развёртывание проекта

1. Сборка проекта

2. Развёртывание на сервере

3. Проверка развёртывания

Внешние ссылки

Справочные ссылки

Оптимизация изображений и медиа

Рекомендации по использованию изображений

Организация и именование изображений

Принципы проектирования таблиц

Таблицы данных

Сложные данные

Контроль версий и совместная работа

Управление версиями документа

Стандарты коммитов в Git

Стандарты совместной работы над документацией

Чек-лист ревью

Языковые версии

Расширенная конфигурация

Оптимизация для поисковых систем

Контроль качества

Чек-лист проверки содержания

Сбор обратной связи

Связанный синтаксис

Инструменты и ресурсы

Инструменты для качества документации

Платформы для совместной работы

Инструменты аналитики

Инструменты автоматизации