Ришат Мухаметшин, руководитель проектов в компании «БИТ Мастер». Очень долгое время я занимался созданием и поддержанием в актуальном состоянии документации к нашей программной продукции — системе автоматизации бизнеса такси. В последние несколько месяцев я постепенно ухожу от этой должности, мне на замену придёт новый будущий специалист, которого я буду обучать. Сам я уже почти всё время исполняю обязанности по руководству проектами.

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

Все эти советы можно отвязать от темы, и они настолько очевидны, что их мог бы дать опытный врач или юрист. Но сколько раз, читая книгу, вы думали о том, что в ней, в общем-то, написаны очевидные вещи, — и сколько раз не могли от неё оторваться?

1. Учите русский язык, конечно же.

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

Учитесь, управляя своей речью, управлять процессом: если вам нужно, чтобы пользователь, читая документацию, выполнил какое-то действие, — начните фразу со слова «выполни», и уж совсем не нужно начинать фразу со слов «здесь можно так», «если вам когда-нибудь захочется, вы могли бы сделать так...». Допускайте альтернативы там, где они допустимы, и требуйте строгого выполнения там, где оно необходимо.

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

2. Всегда представляйте, что вы — пользователь.

Пользователь не знает разных странных слов «тикет», «саппо́рт», «дропдаун» и «бета». Для него они — «задача на доработку», «служба технической поддержки», «выпадающее меню» и «версия для открытого тестирования». Не нравится писать много букв? Используйте макросы, в конце концов, но только не забивайте головы ваших пользователей, которые, кстати, и без того полны разных забот и проблем, ненужной и лишней информацией о тикетах и бетах.

Написав кусок документа, прочитайте его. Всё понятно? Дайте почитать коллеге. Он тоже всё понял? Дайте почитать клиенту. Если и он всё понял, — цель достигнута, вот вам ачивка. Если нет — переделайте. Конечный результат может внезапно оказаться непонятным вам, но если он понятен пользователю, вы всё сделали правильно.

Когда вы начнёте с первого раза писать так, что пользователь поймёт вас, будьте уверены — это первый успех. К тому же, у вас останется больше времени, свободного от переписывания на разные лады одного и того же текста.

3. Стройте документацию по принципу FAQ.

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

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

Эстафету передаю Тане Молодских, HR-менеджеру компании Центр высоких технологий.