Перейти к основному содержимому

6.03. Wiki проекта

ДЛЯ НОВИЧКОВНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНОВ РАЗРАБОТКЕ
Руководителю Аналитику Техническому писателю

Wiki проекта​

В любом проекте разобраться без проблем может только сам создатель, архитектор или разработчик. Но что, если он открытый, с ним работает много людей, неужели придётся всех учить?

Концептуально - Wiki как раз учит. Кроме того, в отличие от обычного README или руководства, это именно систематизированная часть проекта, содержащая инструкции, гайды, пояснения и прочее полезное. Такие Wiki прикрепляют к своему репозиторию с кодом, чтобы другим пользователям было удобнее использовать его и участвовать в работе над проектом.

1. Wiki как элемент инфраструктуры проекта​

Wiki — от гавайского wiki-wiki, «быстро» — изначально задумывалась как инструмент коллективного, оперативного редактирования текстов. В среде разработки программного обеспечения это понятие трансформировалось: wiki перестала быть просто техническим решением и стала контекстуальным репозиторием знаний. Это не просто хранилище текстов, а структурно-семантическая надстройка над кодовой базой, процессами, артефактами и решениями.

Ключевое отличие проектной wiki от других форм документирования — её прямая привязка к жизненному циклу проекта. Она не существует отдельно от кода, задач или архитектуры: она развивается вместе с ними. Если документация — это отчёт о состоянии на момент написания, то wiki стремится быть активной, живой средой, в которой знания обновляются синхронно с изменениями в системе. Отсюда — главная функция: преодоление когнитивного барьера при взаимодействии с проектом.

Этот барьер возникает по трём основным причинам:

  • Объём кодовой базы — даже в проектах среднего масштаба количество файлов, модулей, зависимостей и контекстных решений может быть необозримым уже на этапе ввода в эксплуатацию;
  • Контекстная насыщенность — код сам по себе несёт синтаксис и семантику, но не объясняет мотивации: почему выбран такой алгоритм, почему отвергнута альтернатива, какие компромиссы были приняты;
  • Ротация участников — в реальных командах люди приходят и уходят; знания, передаваемые устно или фиксируемые эпизодически, быстро теряются.

Wiki призвана минимизировать потери, связанные с этими факторами. Она не заменяет исходный код, не дублирует issue-трекер и не подменяет технические спецификации. Она дополняет их, делая явными связи между уровнями абстракции: от стратегических решений до конкретных строк реализации.

2. Wiki проекта против базы знаний и корпоративного Confluence​

На первый взгляд, wiki может показаться разновидностью базы знаний (knowledge base). Действительно, обе структурируют информацию, поддерживают поиск, гипертекстовые ссылки и версионирование. Однако разница лежит в ориентации на контекст и цикл обновления.

База знаний, особенно в enterprise-среде, часто создаётся как универсальный справочник: документы по продуктам, инструкции по внутренним сервисам, регламенты. Её содержание агрегируется из множества источников и предназначено для широкой аудитории — клиентов, поддержки, менеджеров, аналитиков. Обновления происходят эпизодически и, как правило, по инициативе владельца статьи.

Confluence (и аналоги — Notion, Nuclino, BookStack) — это платформа, а не методология. Она может использоваться и как база знаний, и как wiki проекта. Однако, по умолчанию, Confluence фокусируется на коллаборации над документами: совместное редактирование ТЗ, протоколы встреч, roadmaps. Её структура часто иерархична, строится вокруг пространств имён и страниц, а не вокруг артефактов проекта. Связь с кодом, если она есть, реализуется вручную — через вставку ссылок, скриншотов, фрагментов кода.

Wiki проекта, напротив, естественно интегрирована в рабочий поток разработки. В идеале:

  • каждая существенная функциональная единица (модуль, сервис, подсистема) имеет соответствующую страницу;
  • каждая архитектурная диаграмма актуализируется при изменении интерфейсов;
  • каждое крупное решение фиксируется в виде ADR (Architectural Decision Record) — и ссылается на соответствующие коммиты, задачи, PR;
  • изменения в wiki могут триггериться CI/CD-конвейером (например, при мерже в main);
  • поиск в wiki учитывает не только текст, но и топологию репозитория: кто что писал, где использованы одни и те же паттерны и т.п.

Таким образом, wiki проекта — это не «ещё одно место для заметок», а рефлексивная оболочка, обеспечивающая обратную связь между знанием и действием. Она снижает информационную энтропию в проекте, делая знание о системе воспроизводимым и проверяемым.

3. GitHub Wiki: встроенная документация как часть репозитория​

GitHub, как одна из ведущих платформ хостинга исходного кода, предлагает встроенную поддержку wiki для каждого репозитория. Это решение реализовано как отдельный, но сопряжённый Git-репозиторий, размещаемый по адресу https://github.com/<owner>/<repo>.wiki.git.

Это важный технический нюанс: wiki на GitHub — не просто веб-интерфейс, а полноценный Git-репозиторий со своей историей коммитов, ветвями, pull request’ами. Это позволяет:

  • локально клонировать wiki, редактировать файлы в привычной IDE, проверять локальную сборку (например, через gollum, локальный wiki-сервер);
  • применять те же правила ревью кода к документации — через PR к wiki-репозиторию;
  • интегрировать wiki в CI, например, для проверки орфографии, валидности ссылок или соответствия стилю.

По умолчанию доступ к редактированию wiki имеют только участники с правами записи в основной репозиторий, но для публичных проектов можно разрешить редактирование любому авторизованному пользователю GitHub. Это открывает путь к community-driven documentation — когда пользователи, а не только авторы, улучшают описание API, добавляют примеры использования, уточняют edge cases.

Содержимое wiki обычно пишется в Markdown — том же формате, что и README, issue и комментарии. Но в отличие от README, wiki не ограничена форматом: можно использовать расширенные возможности рендеринга — встроенные диаграммы (Mermaid), блок-схемы, интерактивные карты зависимостей (через PlantUML или аналоги), встраивание видео и 3D-моделей (где это уместно — например, при описании геопространственных или графических систем).

Существенным ограничением GitHub Wiki остаётся отсутствие автоматической генерации на основе кода. Всё содержимое — ручное. Даже описание классов или API требует явного написания. Это создаёт разрыв между реальным состоянием кода и документированным состоянием: при устаревании описания — например, после рефакторинга — wiki начинает вводить в заблуждение. Именно этот разрыв и призван устранить новый класс инструментов.

4. Google Code Wiki: переход к агентно-автоматизированной документации​

Недавно Google анонсировал Code Wiki — принципиально иной подход к документированию, который следует рассматривать не как альтернативу GitHub Wiki, а как эволюционный шаг в сторону непрерывно обновляемой, агент-опосредованной документации.

Основная идея Code Wiki — отказ от парадигмы статической документации. Вместо того чтобы поручать людям писать и поддерживать текст, платформа автоматически анализирует репозиторий и генерирует:

  • иерархическую карту проекта — с выделением модулей, компонентов, точек входа;
  • диаграммы: архитектурные (слои, микросервисы), классовые (наследование, композиция), последовательностей (взаимодействие объектов);
  • видео-объяснения — через интеграцию с NotebookLM, где ИИ интерпретирует структуру и генерирует повествовательные пояснения;
  • интерактивные ссылки — каждая сущность в wiki гиперссылается на исходный файл, строку, функцию или даже конкретный commit.

Но главный прорыв — в интегрированном Gemini-агенте, который:

  • обучен на конкретной wiki данного репозитория;
  • имеет доступ к всей текущей версии кода;
  • отвечает не в общих терминах, а в контексте именно этого проекта — с цитированием фрагментов, предложением аналогичных решений в других модулях, объяснением нюансов реализации.

Это не «chat over code», а reasoning engine поверх структурированного знания. Агент не просто ищет похожий код — он рассуждает о намерениях, ограничениях, скрытых зависимостях. Например, на вопрос «Почему для авторизации используется кастомный JWT-валидатор, а не стандартный Spring Security Filter?» он может ответить, сославшись на историю коммитов, обсуждения в PR и упоминания в ADR.

Code Wiki пока доступен только для публичных репозиториев, но Google объявил о скором запуске Gemini CLI extension — локального инструмента для работы с приватными репозиториями. Это критически важно: наибольшую сложность представляет именно legacy-код в корпоративной среде, где исходные авторы ушли, а документация либо отсутствует, либо устарела на годы.

Здесь стоит подчеркнуть: Code Wiki — не замена GitHub Wiki. Это надстройка нового поколения. GitHub Wiki остаётся местом для намеренно написанного, человеко-ориентированного контента: философии проекта, гайдлайнов по вкладу, сценариев использования, сравнений с аналогами. Code Wiki же берёт на себя технически-нейтральное, но объёмное описание как устроено и как работает — и делает это в реальном времени.

5. Оффлайн и локально управляемые wiki-платформы: MediaWiki, BookStack, Docusaurus и другие​

В то время как облачные решения — GitHub Wiki, Google Code Wiki, Notion — обеспечивают удобство и скорость развёртывания, они не всегда соответствуют требованиям корпоративной среды. Причины могут быть различными: политика информационной безопасности, ограничения по передаче данных за пределы инфраструктуры, необходимость кастомизации под внутренние процессы или долгосрочная автономность от внешних провайдеров. В таких случаях предпочтение отдаётся локально управляемым wiki-системам.

MediaWiki: эталонная платформа, проверенная масштабом​

MediaWiki — программное обеспечение, лежащее в основе Википедии, — остаётся де-факто стандартом для крупных, долгоживущих, многопользовательских баз знаний. Её отличает:

  • Модульная архитектура — ядро отделено от интерфейса, расширений и тем оформления;
  • Поддержка семантических метаданных (через расширение Semantic MediaWiki), позволяющая превращать wiki из набора страниц в структурированную онтологию: можно задавать классы сущностей («Сервис», «Микросервис», «Система мониторинга»), их свойства («зависит от», «владеет», «имеет SLA»), строить динамические запросы и отчёты;
  • Гибкая система прав — от глобальных групп пользователей до прав на уровне отдельных страниц и пространств имён;
  • Интеграция с LDAP/Active Directory, SSO, а также возможность подключать кастомные провайдеры аутентификации;
  • Поддержка интернационализации на уровне ядра, что критично для международных проектов.

MediaWiki требует отдельного сервера (обычно LAMP/LEMP-стек), но не накладывает ограничений на хостинг: развёртывание возможно как на физических машинах, так и в контейнерах (Docker), на Kubernetes-кластерах или в облачных VM. При грамотной настройке кэширования (Varnish, Memcached, Redis) и балансировке — масштабируется на десятки тысяч страниц и сотни одновременных редакторов.

Главное преимущество MediaWiki — устойчивость к забвению. Даже если проект будет заброшен на годы, его wiki останется читаемой, так как формат хранения (wiki-разметка, база данных MySQL/PostgreSQL) остаётся совместимым на протяжении десятилетий. В отличие от проприетарных SaaS-решений, где экспорт данных может быть ограничен или невозможен.

BookStack: баланс между удобством и контролем​

Если MediaWiki — это «тяжёлая артиллерия», то BookStack — инструмент для команд, ценящих простоту и понятную структуру. Основанная на PHP и Laravel, BookStack организует контент по трём уровням: Книга → Глава → Страница. Это соответствует естественной иерархии документации: продукт → подсистема → конкретная функция или инструкция.

Особенности BookStack:

  • Визуальный редактор на базе CKEditor (с опциональной поддержкой Markdown);
  • Встроенный поиск с подсветкой контекста и возможностью фильтрации по книгам/пользователям;
  • Управление версиями страниц — каждое изменение сохраняется, возможен diff и откат;
  • Аттачменты — файлы привязываются к страницам и управляются внутри системы;
  • REST API, позволяющий интегрировать BookStack с CI/CD, системами мониторинга или автоматизированными отчётами.

BookStack не пытается заменить issue-трекер или репозиторий кода. Она фокусируется исключительно на хранении и структурировании знаний. Это делает её идеальной для технической документации, инструкций по эксплуатации, внутренних регламентов, описаний API. Особенно ценится в командах, где редакторами выступают не только разработчики, но и аналитики, тестировщики, технические писатели.

Docusaurus и статические генераторы: когда wiki становится частью продукта​

В open-source и продуктовых командах всё чаще документацию не просто размещают, а выпускают как компонент продукта. В этом случае применяются статические генераторы сайтов — такие как Docusaurus (от Meta), VuePress, MkDocs или Sphinx.

Принцип работы прост: исходные файлы документации (в Markdown, иногда с вставками JSX или MDX) хранятся в том же репозитории, что и код (например, в папке docs/). При изменении запускается сборка — и генерируется полностью автономный HTML-сайт, который можно:

  • разместить на GitHub Pages, GitLab Pages, Netlify, Vercel;
  • встроить в корпоративный портал через iframe или reverse proxy;
  • поставлять как часть дистрибутива (локальный docs/index.html).

Преимущества такого подхода:

  • Единый workflow — документация ревьюится вместе с кодом, в том же PR;
  • Версионирование — Docusaurus поддерживает параллельные ветки документации для разных версий продукта (например, v1.0, v2.1, next);
  • Темизация и интернационализация «из коробки»;
  • Поддержка клиентских фич: поиск (через Algolia или локальный индекс), dark mode, sidebar navigation, анонсирование обновлений («What’s new»);
  • SEO-оптимизация — статический HTML индексируется поисковыми системами без проблем.

Важно: статические генераторы — это не «wiki» в классическом понимании (редактирование через веб-интерфейс), но они реализуют ключевую функцию wiki: структурирование знаний вокруг проекта. Разница лишь в том, что редактирование происходит не в браузере, а в IDE или текстовом редакторе — что для многих разработчиков является плюсом, а не минусом.

Такой подход широко используется в экосистемах: React, Babel, Node.js, ELMA365 SDK, BPMSoft API Docs — все они применяют Docusaurus или аналоги. Это свидетельствует о зрелости парадигмы: документация — не приложение, а первоклассный артефакт.

6. Wiki как среда для фиксации архитектурных решений (ADR)​

Одна из наиболее ценных, но недооценённых практик — ведение Architectural Decision Records (ADR). Это краткие, структурированные тексты, фиксирующие ключевые технические решения, принятые в проекте: выбор БД, паттерн взаимодействия между сервисами, подход к авторизации, отказ от определённого фреймворка и т.д.

ADR не описывает как реализовано, а объясняет почему так, а не иначе. Формат типичного ADR (по шаблону Майкла Найгарда) включает:

  • Дата и номер — для хронологического порядка;
  • Статус (proposed, accepted, superseded, deprecated);
  • Контекст — какая проблема/ограничение требует решения;
  • Решение — выбранная альтернатива;
  • Последствия — плюсы, минусы, влияние на сопровождение, масштабируемость, безопасность.

Существенно, что ADR — не разовые заметки. Они жестко привязаны к истории проекта: каждая запись ссылается на соответствующие коммиты, PR, обсуждения в трекере. В wiki ADR обычно размещаются в отдельной секции (например, /adr/0001-use-postgres.md), и автоматизированные инструменты (например, adr-tools) позволяют генерировать оглавление, отслеживать статусы, строить граф зависимостей решений.

Польза ADR двояка:

  • Для новых участников — возможность быстро понять логику архитектуры, не задавая вопросов «а почему у нас так?»;
  • Для аудита и рефакторинга — при рассмотрении изменения (например, миграции с REST на gRPC) можно оценить, какие ADR затрагиваются, какие компромиссы потребуется пересмотреть.

Wiki, поддерживающая ADR, превращается в архитектурный журнал — источник доверия и прозрачности. Это особенно важно в распределённых командах и проектах с долгим жизненным циклом.

7. Версионирование и ветвление документации​

Один из фундаментальных принципов качественной документации — согласованность с версией кода. Документация для версии 2.3 не должна описывать фичу, появившуюся только в 3.1. Для этого применяются те же инструменты, что и в разработке: ветвление и тегирование.

В случае GitHub Wiki — поскольку это отдельный Git-репозиторий — можно создавать ветки вручную (release/2.3, main) и переключаться между ними. Однако это требует дисциплины: забытый мерж из main в release/2.3 приведёт к рассогласованию.

В Docusaurus или MkDocs версионирование поддерживается на уровне конфигурации: при тегировании релиза (git tag v2.3.0) запускается CI-задача, которая копирует текущее состояние docs/ в versioned_docs/v2.3/, а также сохраняет sidebar и переводы. На сайте появляется переключатель версий — пользователь сам выбирает, какую документацию читать.

Для MediaWiki и BookStack ветвление сложнее: они работают с единственным состоянием базы. Здесь возможны два подхода:

  • Отдельные инстансы — для критически важных релизов развёртывается изолированная копия wiki (например, docs-v2.example.com);
  • Метки на уровне страниц — каждая страница помечается тегами (ver:2.0+, deprecated-after:3.1), а фильтр в поиске/навигации скрывает устаревшее.

Выбор стратегии зависит от требований: если продукт имеет долгосрочную поддержку нескольких мажорных версий (LTS), версионирование обязательно. Если это библиотека с быстрым циклом релизов — достаточно поддерживать только latest и next.

8. Автоматизация наполнения: от кода к документации и обратно​

Если wiki рассматривать как живую надстройку над проектом, то её наполнение не может полагаться исключительно на человеческий фактор. Даже самая дисциплинированная команда неизбежно отстаёт от темпа изменений в коде — особенно в условиях CI/CD с ежедневными релизами. Поэтому критически важна автоматизация генерации и синхронизации контента.

Генерация API-документации из исходного кода​

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

  • Javadoc / Dokka / Sandcastle — для Java, Kotlin, C# соответственно;
  • Sphinx + autodoc — для Python;
  • TypeDoc / JSDoc — для TypeScript и JavaScript;
  • Doxygen — кроссплатформенный инструмент, поддерживающий более 25 языков, включая C++, PHP, Objective-C.

Эти системы читают аннотации (/// <summary>, /** @param */, """ Docstring """), извлекают типы, зависимости, наследование, и формируют HTML/Markdown-структуру. Современные генераторы (например, TypeDoc) умеют строить графы зависимостей между модулями, отображать перекрёстные ссылки, встраивать примеры из unit-тестов.

Однако важно понимать: такая документация описывает интерфейс, но не намерение. Она отвечает на вопрос «что делает метод?», но не на «почему он сделан именно так?». Поэтому автоматически сгенерированные API-справочники лучше всего размещать как приложение к основной wiki — например, в разделе /api/, с прямыми ссылками на соответствующие архитектурные страницы.

Интеграция с OpenAPI и спецификациями API​

Для REST/gRPC/GraphQL-сервисов центральным артефактом становится спецификация интерфейса: OpenAPI (ранее Swagger), Protocol Buffers, GraphQL Schema. Эти форматы — не просто описания, а исполняемые контракты: из них можно генерировать клиентские SDK, серверные заглушки, тестовые сценарии, валидаторы.

Wiki может интегрироваться с такими спецификациями двумя способами:

  1. Эмбеддинг рендерера — например, встраивание Swagger UI или Redoc в страницу wiki. Это обеспечивает всегда актуальное представление API без копирования описаний вручную.
  2. Извлечение контекста — парсер спецификации может автоматически формировать:
    • описание ресурсов и операций;
    • примеры запросов/ответов (на основе examples в OpenAPI);
    • схемы валидации (JSON Schema → пояснения о форматах полей);
    • зависимости между эндпоинтами (например, /orders/{id} требует существующего /users/{id}).

При изменении спецификации — например, добавлении нового заголовка X-Trace-ID — пересборка документации происходит автоматически. Это исключает рассогласование между реализацией и описанием.

Генерация архитектурных диаграмм из кода и метаданных​

Визуализация — один из самых эффективных способов передачи сложных связей. Ручное рисование диаграмм в draw.io или PlantUML не масштабируется: после трёх-четырёх рефакторингов они устаревают.

Современные подходы основаны на статическом анализе кода:

  • Structurizr (от Мартина Фаулера) — позволяет описать архитектуру в коде (C#, Java, Python), а затем визуализировать как C4-диаграммы (Context, Containers, Components, Code); изменения в коде → перестройка диаграммы.
  • Code2flow / Pyan / ts-graphviz — строят графы вызовов функций для конкретных модулей.
  • Dependency-cruiser / Madge — анализируют зависимости между файлами и пакетами, выявляют циклические импорты, «тяжёлые» модули.
  • Mermaid Live Editor + CI-интеграция — генерируют .mmd-файлы из метаданных (например, из package.json, pom.xml, docker-compose.yml) и коммитят их в wiki-репозиторий.

Google Code Wiki, упомянутый ранее, использует гибридный подход: статический анализ + ИИ-интерпретация. Например, при обнаружении паттерна Producer–Consumer в коде система не просто строит диаграмму последовательности, но и помечает её как таковую, добавляя пояснение: «Асинхронная обработка через очередь; производитель не блокируется при отправке».

Синхронизация с issue-трекером и CI/CD​

Wiki становится по-настоящему «живой», когда интегрируется в рабочий цикл:

  • При создании задачи в Jira или GitHub Issues можно автоматически генерировать черновик страницы wiki (например, для нового модуля), заполняя шаблон: цель, требования, ожидаемые риски.
  • При мерже в main CI-конвейер может:
    • обновить версию в заголовке документации;
    • проверить ссылки на файлы (не удалён ли описанный класс?);
    • запустить линтер Markdown (например, markdownlint-cli);
    • отправить уведомление в Slack: «Обновлена документация по модулю Auth — [ссылка]».
  • При деплое релиза — автоматически обновлять Release Notes на wiki, извлекая changelog из conventional commits.

Такая интеграция превращает wiki из пассивного хранилища в активный участник процесса: она не ждёт, пока кто-то напишет — она реагирует.

9. Метрики эффективности: как оценить, работает ли wiki​

Внедрение wiki — это инвестиция. Чтобы оценить её окупаемость, необходимы измеримые показатели. Ниже — набор практических метрик, применимых в реальных проектах.

Операционные метрики​

  • Время первого коммита нового участника — среднее количество часов/дней от присоединения к команде до первого успешного PR. Снижение этого показателя напрямую коррелирует с качеством вводной документации.
  • Доля PR без комментариев «объясните, зачем это нужно» — косвенный индикатор того, насколько хорошо зафиксированы архитектурные контексты.
  • Частота обращений к разделам wiki в поиске (через Google Analytics, Matomo или внутренний логгер) — высокий трафик на страницу /legacy/ может сигнализировать о проблемах сопровождения.

Качественные метрики​

  • Процент страниц с датой обновления за последние 90 дней — индикатор актуальности. Значение < 40 % говорит о «застое».
  • Соотношение «рукописных» и «сгенерированных» страниц — в зрелой системе автоматически поддерживаемые разделы (API, диаграммы) должны составлять не менее 60 % объёма.
  • Наличие ADR для всех мажорных изменений за год — если их нет, значит, архитектурные знания остаются в головах.

Социальные метрики​

  • Количество уникальных авторов за квартал — если правят только 1–2 человека, wiki не стала частью культуры.
  • Доля внешних контрибьюторов, редактировавших wiki (в open-source) — показатель прозрачности и welcoming-культуры.
  • Обратная связь в опросах — например, в ежеквартальном NPS для внутренних пользователей: «Насколько легко вам найти информацию о системе X?» (шкала 1–5).

Важно: метрики не должны использоваться для наказания или формального отчёта. Их цель — диагностика: где wiki помогает, а где — создаёт иллюзию порядка.

10. Социальные практики: как сделать wiki частью культуры​

Технические решения — лишь половина успеха. Даже идеально настроенная платформа останется пустой, если команда не будет хотеть в неё писать. Поэтому ключевую роль играют организационные и поведенческие практики.

Wiki как часть Definition of Done​

Наиболее эффективный приём — включить обновление документации в DoD (Definition of Done) для задачи:

  • Для фичи: «Добавлено описание в раздел /features/, обновлена диаграмма компонентов, зафиксирован ADR, если решение нетривиально»;
  • Для багфикса: «Описан сценарий воспроизведения и root cause в разделе /known-issues/»;
  • Для рефакторинга: «Актуализированы ссылки и диаграммы, устаревшие страницы помечены как deprecated».

Это переносит ответственность с «кого-то» на конкретного исполнителя задачи — того, кто лучше всего знает контекст.

Ритуалы и ревью​

  • Wiki-ревью раз в квартал — как часть ретроспективы: «Какие 3 страницы устарели больше всего? Кто может их обновить?»;
  • Ролевая практика — назначение «wiki-стюарда» на спринт: не для написания, а для координации, напоминаний, помощи в оформлении;
  • Примеры из практики — в onboarding-программе показывать не только код, но и как искать знания: «Вот как найти ADR по выбору очереди сообщений», «Вот как проверить, актуальна ли инструкция по деплою».

Минимизация трения​

  • Использовать единый формат (Markdown) и единый редактор (IDE с поддержкой предпросмотра);
  • Обеспечить быстрый preview (например, локальный npm run docs:dev для Docusaurus);
  • Автоматизировать рутину: генерация TOC, проверка dead links, орфография;
  • Разрешить «черновики» — страницы в состоянии draft или в отдельном пространстве /sandbox/, где можно экспериментировать без страха перед публикацией.

Главный принцип: wiki должна быть удобнее, чем Slack-сообщение в канале. Если новому участнику проще спросить в чате, чем найти ответ — система не работает.