Как вносить правки в документацию
Актуально на: 2026-07-23
Документация лежит в репозитории как Markdown. Внести правку можно тремя способами — выбери по своему уровню. Все три ведут к одному результату: изменение проходит ревью и попадает в main.
Тир 1 — полный git (разработчики, технические аналитики)
Как с кодом:
git checkout -b docs/<короткое-описание>
# правишь файлы в docs/
git add docs/
git commit -m "docs: <что изменил>"
git push -u origin docs/<короткое-описание>Затем открываешь Pull Request. Правки к докам можно и нужно класть в тот же PR, что и связанное изменение кода (doc near code).
Тир 2 — веб-редактор GitHub (аналитики, «немного знаком с git»)
Git локально ставить не нужно.
- Открой нужную страницу в репозитории на github.com.
- Нажми карандаш ✏️ (Edit this file) справа сверху.
- Правь текст прямо в браузере. Markdown — это обычный текст:
# Заголовок,- список,**жирный**. - Внизу нажми Commit changes → Create a new branch and start a pull request.
Дальше PR посмотрит кто-то из команды. Ошибиться сложно — ничего не ломается до слияния.
Мини-шпаргалка по Markdown:
| Хочу | Пишу |
|---|---|
| Заголовок | # Заголовок, ## Подзаголовок |
| Список | - пункт |
| Ссылка | [текст](адрес) |
| Жирный / курсив | **жирный**, *курсив* |
| Таблица | `\ |
Тир 3 — черновик без Markdown (нетехнические участники)
Если git и Markdown — барьер, не мучайся форматированием:
- Напиши как умеешь (хоть сплошным текстом) и положи файл в
inbox/, или - Скинь текст ответственному за доки — он оформит и разложит по структуре.
Owner документации разбирает inbox/ и переносит содержимое в нужный раздел.
Куда какой раздел
См. карту в README.md. Если сомневаешься — клади в inbox/, разберут.
Общие правила
- Новый термин — сначала добавь его в
domain/glossary.md. - Архитектурное решение — оформи как ADR, а не разрастающийся аудит-файл.
- Устарело — переноси в
archive/, не удаляй.