StaticGen is a leaderboard of the top open source static site generators. Promoting a static approach to building websites.

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

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

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

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

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