Безопасность в документации

Роли доступа

В целом в IT хорошим тоном считается ограничивать доступы к коду — представьте, что кто-то по незнанию или неосторожности внесёт какие-то изменения на главную страницу крупной компании. Или по злому умыслу добавит туда же заведомо ложные сведения, порочащие честь и достоинство другого лица или подрывающих его репутацию.

Поэтому по-умолчанию доступ к продовым текстам должен быть закрыт. Дальше появляется роль Писатель — человек, который может вносить изменения. И роль Редактор — для проверки и подтверждения правок. У Писателя не должно быть возможности выкатить что-то в прод без подтвержения! При этом Писатель для одной задачи, может быть Редактором для другой, но не для своей.

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

Матрица согласований

Заказчик — человек, который инициирует изменения документации. Это может быть и технический писатель, и его руководитель, и представитель бизнеса, и случайный пользователей, обнаруживший опечатку. Однако не все эти люди знают всё о продукте документации. Поэтому следует составить и поддерживать матрицу согласований — простую таблицу где-то в пространстве технических писателей с людьми, отвечающими за разные части продукта и не выпускать тексты в прод без трёх подтверждений: от Редактора, Заказчика и Держателя знания.

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