База знаний

Хорошее описание задачи отделяет проблему от предполагаемого решения. Оно помогает участникам одинаково понимать, что должно измениться.

1. Контекст: что происходит сейчас и кого это затрагивает.
2. Результат: какое изменение необходимо получить.
3. Ограничения: сроки, доступные ресурсы и зависимости.
4. Критерии готовности: как проверить, что задача решена.

Неизвестные условия лучше записать отдельными вопросами, а не заменять предположениями.

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

• Назначение: для чего нужен документ и кому он адресован.
• Область применения: где инструкция действует, а где нет.
• Основная часть: последовательность действий или описание решения.
• Проверка: ожидаемый результат и способы его подтвердить.
• Связанные материалы: определения, зависимости и исходные требования.

Название должно помогать найти материал без знания его внутреннего устройства.

Запись о решении не должна повторять весь ход обсуждения. Достаточно сохранить существенные условия, выбранный вариант и ожидаемые последствия.

• Проблема и условия, при которых потребовалось решение.
• Рассмотренные варианты и причины отказа от альтернатив.
• Принятый подход и его ограничения.
• Условия, при которых решение стоит пересмотреть.

Если обстоятельства изменились, добавьте новую запись со ссылкой на предыдущую, а не переписывайте историю выбора.

Перед передачей результата проверьте не только наличие файлов, но и возможность пользоваться ими без дополнительных пояснений.

• Указаны актуальная версия и назначение каждого материала.
• Описаны запуск, использование или порядок дальнейшей работы.
• Зафиксированы выполненные проверки и известные ограничения.
• Перечислены зависимости и необходимые доступы без публикации секретов.
• Понятно, какие вопросы остаются открытыми.

Пароли и приватные ключи не включаются в общую документацию. Для них используются отдельные защищённые каналы хранения и передачи.

Выберите раздел слева или откройте все документы. Поиск работает по заголовкам и полному тексту материалов; при вводе запроса поиск охватывает весь справочник.

Карточка раскрывается кнопкой «Открыть документ». Для перехода с клавиатуры используйте Tab, для раскрытия — Enter или пробел.

Без JavaScript материалы остаются доступны целиком через раскрываемые карточки. Запросы поиска обрабатываются в браузере и не отправляются на сервер.

Обновляйте описание вместе с изменением самого процесса. Небольшая актуальная инструкция полезнее подробного документа, который больше не соответствует работе.

• Перед изменением определите, какие разделы затронуты.
• Проверьте примеры и последовательность действий.
• Уберите противоречащие новому порядку рекомендации.
• Отдельно укажите важные отличия от предыдущего подхода.

Не добавляйте в общедоступные материалы персональные данные, внутренние адреса и сведения, для которых требуется ограничение доступа.