# Принципы написания технической документации

### 1 Мы следуем принятым принципам

Персональное несогласие — не причина отступать от принципов. Тем не менее, можно начать обсуждение любого принципа, если изменились обстоятельства и он перестал быть полезным.

### 2 Мы пишем документацию осознанно, а не наугад

Мы разбираемся детально, почему что-то так работает и выясняем причины, если что-то работает не так. Не добавляем строки с мыслью “это может помочь” и не удаляем строки с мыслью “кажется, это не нужно”.

### 3 Читаемость важнее скорости и краткости

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

#### 3.1 Мы не оставляем белых пятен

Мы избегаем абстрактных и не до конца понятных формулировок. Задаём вопросы, ресёрчим, высказываем сомнения. Потратим время сейчас — сэкономим потом.

#### 3.2 Мы избегаем повторений

Мы не пишем в документации одно и то же несколько раз, создаём ссылки.

#### 3.3 Мы пишем понятную документацию для всех

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

#### 3.4 Мы ревьюим документацию

Мы делимся написанной документацией с заинтересованными сторонами с целью подтвердить, что в документации рассмотрены все вопросы и ничего не забыто. После этого мы просим незаинтересованного человека. Учитываем обратную связь.