Не начинайте писать документацию! Сначала ответьте на два простых... Мастер-классы

Доклад принят в программу конференции
Семён Факторович
documentat.io

Пять лет писал на C++, а потом добровольно и осознанно стал техническим писателем (да, так бывает!).

С 2012 до 2018 руководил отделом технической документации в Zodiac Interactive.

В 2018 году вместе с партнером основал компанию по заказной разработке документации и консалтингу в этой области.

Telegram @factorized

Twitter @lazeez
Тезисы

Все мы сходимся на том, что документация — это хорошо и полезно.

Как написать документацию так, чтобы она на самом деле была хорошей и полезной — очень сложный и многогранный вопрос. Чтобы подойти к ответу на него, нужно задуматься о двух вещах: кому мы пишем документацию и зачем мы ее пишем. Другими словами, написание документации (как и любую другую проектную активность) нужно начать с ее целеполагания.

На этом мастер-классе мы поговорим вот о чем:
- С каких сторон нужно изучить вашу проектную ситуацию, чтобы понять, какая документация вам нужна?
- Как идентифицировать читателей документации и понять их нужды?
- Как писать документацию, чтобы она максимально хорошо решала задачи читателей?
- Как писать документацию, чтобы она максимально хорошо решала задачи бизнеса?

В первой части мастер-класса я расскажу, как мы отвечали на эти вопросы в проектах, в которых я участвовал в последние 8-9 лет.

Во второй части мастер-класса мы будем рассматривать проектные ситуации, случавшиеся у вас (т.е. участников мастер-класса) и отвечать на те же самые вопросы, но в ваших реалиях.

Подготовительное задание

Сделайте небольшой реестр текущей документации (или видов документации) в вашем проекте.

Это могут быть справочники по API, требования и ТЗ, пользовательская документация, документация дизайн-решений для разработчиков, комментарии к коду и пр.

По каждому виду документации подумайте, кто ее читатель и зачем эта документация этому читателю.

Другие доклады секции Мастер-классы

CLI в Node.js
Александр Коржиков
Dev IT Engineer ING Group (Нидерланды)