Дисклеймер: Все описанное ниже не относится к проектам, в которых документация ведется по ГОСТ. Если ты работаешь по ГОСТ, то можешь листать дальше. Тебе поможет только помощь IT богов (на прощание крепко обнял тебя пустив сочувственную слезу техписа).

Всем привет! Меня зовут Игорь. Я технический писатель ITM. Сегодня я хочу поднять тему ведения документации на проекте и разобраться в самой сути этого процесса. Я уверен, что изложенные ниже тезисы будут крайне полезны не только тем, кто непосредственно занимается документированием, но и тем, кто руководит командами.

Игорь

Технический писатель

1. А чем вообще занимается технический писатель?

Если спросить Яндекс, то получим вот такой ответ: «Технический писатель занимается составлением технической документации для передачи сложной технической информации в понятной пользователям форме». Я с таким определением не согласен. Более того, я вообще считаю, что термин «технический писатель» слишком всеобъемлющий, поскольку включает в себя тех, кто ведет документацию на IT проекте, и тех, кто пишет эксплуатационную документацию для самолетов. Думаю, всем очевидно, что это совершенно разные компетенции и навыки и что замена одного на другого просто невозможна.

Если бы меня попросили заново придумать название для совей должности, я бы остановил свой выбор на «специалист по информационному обмену», поскольку именно этот термин наилучшим образом описал бы то, чем занимается техпис в IT команде. Конечно, если речь идет о хорошем техписе (об этом мы и будем говорить далее).

Почему было так важно говорить обо всех этих терминах? (можно закрыть форточки, духоты больше не будет). Все просто. Без этого невозможно понимание того, чем вообще должен заниматься технический писатель в IT проекте. Поскольку если мы придерживаемся общепринятого определения, то получается, что конечная цель работы техписа – это созданный им документ. Но такой подход крайне вреден. Конечная цель техписа – улучшение информационного обмена в команде. А документ – лишь один из многих ИНСТРУМЕНТОВ, помогающих в достижении этой цели.

2. Когда документ считается готовым?

На первый взгляд, крайне глупый вопрос. Все ведь очевидно. Когда его написали и опубликовали. Но боюсь с таким подходом хорошим техписом вам не стать. Работу над документом можно считать завершенной, только когда его начинают активно использовать, а самое главное, получать из него нужную информацию. Поэтому, хороший технический писатель должен позаботиться не только о том, чтобы документ был написан, но и о том, чтобы доставить этот документ конечному пользователю, потребность которого должна быть закрыта этим документом (да, мысль сложная поэтому лучше перечитать еще разок). Иначе вашу работу можно будет сравнить с программистом, который каждый день пишет код, но не сливает его на прод.

3. Чем больше, тем хуже

Когда команда приходит к пониманию того, что им необходимо вести документацию, возникает соблазн описать вообще все. Более того, технический писатель, который сам не до конца понимает в чем заключается его работа (см. пункт первый), стремится создать как можно больше документов (ведь это его цель). Но документации не должно быть много, ее должно быть ДОСТАТОЧНО. В противном случае, вы лишь создаете «информационный шум», в котором очень сложно будет найти то, что действительно нужно в данный момент. Отсюда вытекает наш следующий пункт.

4. Документ отвечает на вопросы, а не порождает их

Как понять, что документации достаточно? Все просто. Документов должно быть столько же, сколько и вопросов. Если у разработчика или пользователя возникает какой-либо вопрос, и он не находит на него ответа – это однозначный сигнал к тому, что нужно создавать документ. Но если, вы создали документ, а вопросов стало еще больше, то боюсь вы работаете в минус. И если вопросы уточняющие, то это дело поправимое. Вам просто нужно доработать документ так, чтобы их закрыть. Но если возникает вопрос: «А зачем нам вообще этот документ?», то боюсь у вас серьезные проблемы, которые требуются кардинального пересмотра процесса документирования.

5. Не кусай больше, чем сможешь проглотить

Ну ладно. С принципом достаточности мы вроде разобрались. Но нужно еще и здраво оценить свои силы. Важно понимать, что документация будет работать только в том случае, если она будет всегда оставаться актуальной. Поэтому, планируя объем документации на проекте, подумайте о том, а достаточно ли у вас ресурсов, чтобы обслужить этот объем. Потому что недостоверная информация, куда опаснее, чем ее отсутствие.

6. Часть команды! Часть корабля!

Поскольку мы говорим о процессах документирования именно в IT проектах, нужно раз и навсегда зарубить себе на носу, что разработка документации – это в первую очередь РАЗРАБОТКА. И в ней должны быть все те же стадии, что и в разработке ПО:

  1. Выявление потребности (см. пункт 4).

  2. Формирование идеи (каким образом мы будем покрывать эту потребность).

  3. Сбор требований (прежде чем писать документ, вы должны четко понимать, кто и как им будет пользоваться и какие функции будет выполнять этот документ).

  4. Реализация (садимся и пишем).

  5. Тестирование (исправляем ошибки и даем критическую оценку того, насколько документ соответствует требованиям).

  6. Демо (даем ознакомиться заинтересованным лицам и собираем обратную связь).

  7. Доставка пользователю.

И самое главное, процесс разработки документации должен быть синхронизирован с процессом разработки ПО. Если разработка идет по вотерфолу, документацию пишем в самом конце. Если разработка идет итерациями, то и документация должна развиваться итеративно.

7. Не рой яму другому. Рой яму себе

Ключевым показателем качества информационного обмена является фактор автобуса. Про него уже много писали и до меня, поэтому просто скажем кратко, что работу по улучшению информационного обмена можно считать завершенной только в том случае, если любого члена вашей команды можно заменить другим сотрудником той же квалификации. Т.е. если наступит страшный день, когда вашего ведущего разработчика собьет автобус, вы должны быть к этому готовы и заранее задокументировать все его знания по вашему проекту. И так еще раз. Вы должны иметь возможность замены любого сотрудника. ЛЮБОГО. Даже вас. Поэтому как бы страшно это не звучало, но процессы документирования тоже нуждаются в документировании. Однако многие техписы даже не задумываются об этом (ну или специально «забывают», чтобы стать незаменимыми).

В целом, получилось кратко и по существу. Однако, я уверен, что многих эта статься подтолкнет к размышлению. Всем, спасибо! Комментарии пишем. Минусы не ставим :-)