База знаний

Как работать с документацией (для команды)

Properties2
tagstubecrown, мета, навигация, процессы
aliasesКак работать с документацией, Как вносить изменения, Contributing, Гайд для команды, Workflow

время чтения ~5 мин.

Как работать с документацией (для команды)

Эта документация живёт в git-репозитории на Bitbucket (cdtraffic/obsidian) и редактируется в Obsidian. Здесь — как ею пользоваться, как вносить правки и что нужно сделать каждому.

📖 Только читать? Просто открой сайт

Вся документация опубликована на https://quartz.tubecrown.com (вход по рабочей Gmail-почте). Ничего устанавливать и настраивать не нужно — заходи и читай, на сайте всегда актуальная версия.

Будешь сам(а) вносить правки? Тогда нужно один раз всё настроить по инструкции ниже. ⬇️

🧠 Главное в двух словах

  • Репозиторий на Bitbucket — единый источник правды. Там «официальная» версия документации.
  • Твоя папка Obsidian — это локальная копия (клон) репозитория. Когда ты редактируешь заметки в Obsidian, ты меняешь файлы у себя на компьютере.
  • Твои правки видят другие только после того, как они отправлены в репозиторий (commit + push).
  • Чужие правки ты получаешь, забрав свежую версию (pull).

Аналогия

Это как общий Google-документ, но «сохранить для всех» происходит не автоматически: сначала ты забираешь свежую версию (pull), правишь, потом отправляешь свою версию обратно (push).

✅ Что нужно сделать один раз, если собираешься писать документацию (онбординг)

  1. Получить доступ к репозиторию cdtraffic/obsidian у техлида.
  2. Установить git и настроить SSH-ключ для Bitbucket (chatgpt или Claude поможет; ключ нужен, чтобы пушить без пароля) либо пользоваться https и каждый раз использовать пароль.
  3. Склонировать репозиторий в удобную папку: 
    git clone git@bitbucket.org:cdtraffic/obsidian.git
  4. Открыть склонированную папку как хранилище (vault) в Obsidian: Obsidian → Open folder as vault → выбрать корневую папку репозитория.
  5. Готово. Все заметки лежат в подпапке content/ (разделы NN — …). В корне репозитория — служебные файлы Quartz (quartz/, quartz.config.yaml и т.п.), их трогать не нужно (в Obsidian они скрыты).

Личные настройки Obsidian (раскладка окон) не синхронизируются между людьми специально — они в .gitignore. У каждого свой вид, и это нормально.

Сайт обновляется сам

После push в main срабатывает автосборка (Bitbucket Pipelines → Cloudflare Pages), и сайт quartz.tubecrown.com обновляется обычно за пару минут. Подробности деплоя — в файле DEPLOY.md в корне репозитория.

🔄 Рабочий цикл (каждый раз, когда что-то меняешь)

Наша модель: изменения идут прямо в ветку main. Поэтому порядок такой:

  1. Перед началом работы — забрать свежую версию (чтобы не разойтись с коллегами): 
    git pull
  2. Создать / отредактировать заметки в Obsidian как обычно.
  3. Отправить изменения в репозиторий (commit + push).

Если работаешь со мной (Claude)

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

  • «Обнови документацию из репозитория» → я сделаю git pull.
  • «Создай заметку про …» / «поправь в заметке …» → я внесу правки.
  • «Сохрани изменения в репозиторий» / «закоммить и запушь» → я сделаю commit + push в main. Я сам слежу за тем, чтобы сначала забрать свежую версию и не сломать чужие правки.

🆕 Как добавить новую заметку (соглашения)

Чтобы база оставалась аккуратной и связной, при создании новой заметки:

  1. Выбери раздел — положи файл в подходящую папку NN — Раздел (если темы нет — предложи новый раздел, согласуем).
  2. Возьми за основу Шаблон заметки (скопируй и заполни).
  3. Заполни «шапку» (frontmatter):
    • aliases — синонимы, по которым заметку будут искать и ссылаться;
    • tags — теги (используй уже существующие, см. ниже);
    • source — откуда информация.
  4. Структура заметки: заголовок #, резюме > [!info], тело с разделами ##.
  5. Свяжи с другими заметками — в конце блок ## 🔗 Связанные заметки со ссылками [[...]].
  6. Добавь заметку в 🏠 Главная — в нужный раздел, чтобы её было видно из карты.
  7. Сохрани изменения в репозиторий (попроси меня или сделай commit + push).

Используй существующие теги

#процессы #команда #финансы #партнёры #абузы #модерация #ранжирование #трейды #инфраструктура #справочник #реклама #seo #qa #инструкция #автоматизация. Новый тег заводи, только если ни один не подходит.

📏 Правила для всех

  • Всегда pull перед работой. Это главный способ избежать конфликтов.
  • Одна тема — одна заметка. Не сваливай разные процессы в один файл.
  • Переименовывай/перемещай файлы через Obsidian, а не вручную в файловой системе — Obsidian сам обновит все [[ссылки]]. Ручное переименование их ломает.
  • Не коммить личные настройки — они уже в .gitignore.
  • Чувствительные заметки (внутренняя логика, рейты, доступы, финансы) — только для команды, не пересылай партнёрам/юзерам.
  • Пиши понятный комментарий к изменению (commit message). Если коммичу я — я сформулирую сам.

❓ Частые ситуации

🔗 Связанные заметки

Источник: внутреннее соглашение команды о работе с документацией.

Вид графа

Обратные ссылки