Документация для SRE
#seeking_sre #sre

В сентябре 2018 года вышла книга Seeking SRE от издательства O'Reily. В ней есть целая глава про документацию команды SRE.
Буду понемногу конспектировать-переводить эту главу. Вот первая часть.

Часть 1/21. Качество документации
Как определить качество командной документации? Есть два аспекта качества:

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

2. Функциональное качество. Хорошая документация решает задачу, для которой написана.
Например, для оценки качества плейбука (playbook, runbook) стоит задать такие вопросы:
— Покрывает ли 100% возможных алертов (alerts, чрезвычайных ситуаций)?
— Может ли команда полагаться на этот плейбук для решения своих задач?
— Насколько плейбук «highly available».
Если дока по починке k8s лежит в wiki, которая хостится в этом же k8s, то когда тот упадёт, дока будет недоступна.
— Насколько легко добавлять и обновлять документы?
— Насколько описание каждого алерта точное и полное?
— Даёт ли каждый документ достаточно информации, чтобы понять и разрешить алерт?
— Есть ли в документе инструкции по эскалации?

Функциональное качество важнее структурного:

Хорошая структура + плохое содержание = плохая документация.
Так себе структура + хорошее содержание = хорошая документация.
Отличная структура + отличное содержание = идеальная документация. Но она бесконечно дорогая и недостижима на практике, как 100% доступность/аптайм.

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

Спасибо Игорю Курочкину из Express42 за то, что порекомендовал мне эту книгу. Кстати, в ближайшую неделю её можно будет купить в составе Humble Bundle: DevOps by O'Reilly.

Приходите обсуждать SRE-доки в чат @docsascode.