Выслушайте меня, прежде чем сказать, насколько я ошибаюсь.
За последние пару недель я прочитал несколько разных статей о написании хорошей пользовательской документации с точки зрения разработчика программного обеспечения. Это область, в которой мне всегда говорили, что я преуспеваю, от людей, которые читали документы, которые я писал на протяжении многих лет. Однако к тому времени, когда я ушел из своего более чем десятилетнего бизнеса WordPress, я почти полностью перестал писать пользовательскую документацию. Похоже, что немногие пользователи заметили или задались вопросом, почему нет пошаговых объяснений определенных функций.
Как и многие разработчики плагинов и тем WordPress, я твердо верю в наличие документации. Как человек, который занимается кодом с 2003 года, документация была моим лучшим другом. За свою карьеру я написал не менее нескольких сотен руководств или страниц документации. Я опубликовал две книги по развитию и был техническим редактором третьей. Я почти уверен, что создал один или два плагина с большим количеством встроенной документации, чем фактический код.
Однако я также поддерживал конечных пользователей более десяти лет. Я с уверенностью усвоил одну вещь: многие пользователи просто не читают документацию. Даже если бы они его читали, большую часть времени они не должны были нуждаться в этом.
Несмотря на то, что я повторяю, изменяя дизайн и пробуя свои силы во всем, чтобы вести пользователей к документации, прежде чем обращаться на форум поддержки с каждым вопросом, повторяющиеся вопросы никогда не перестают попадать в очередь поддержки каждый день.
Мне потребовались годы – намного больше, чем следовало бы, – чтобы понять, что решения нет в документации, и проблема не в способности пользователя прочитать его. Проблема была в продукте. Если пользователи задавали повторяющиеся вопросы, это означало, что с пользователем что-то не так. В конце концов я сместил фокус. Вместо того, чтобы писать больше документов, я сосредоточился на решении проблем, которые продолжали возникать в программном обеспечении.
Деятельность, в которой я потерпел неудачу, – это слушание.
Один из лучших навыков, который может получить разработчик, – это способность слушать, а затем переводить то, что говорят пользователи, в лучший код, пользовательский интерфейс и взаимодействие с пользователем.
В молодые годы – а я подозреваю, что многие разработчики были такими же, когда начинали – я чувствовал, что знаю ответ на каждый вопрос и всегда был прав. Я был высококвалифицированным специалистом и знал это. Для молодого 20-летнего разработчика это означает проблемы. Это означает, что вы считаете, что проблема не в том, что вы построили. Нет, проблема в том, что пользователь что-то делал не так. Это типы разработчиков, которые говорят «RTFM» и указывают пользователю на слишком технический документ, который не решает их проблемы.
Некоторые уроки усваиваются трудным путем, но мы должны их усвоить, чтобы создавать лучшие продукты.
Я обещаю, что если вы выполните одно действие – слушайте, действительно слушайте – пользователей, вы потратите гораздо меньше времени на объяснение того, как что-то работает. Вопрос, который вам нужно задать себе, заключается в том, зачем вообще должна существовать часть документации. Если для объяснения функции требуется 500 слов, велика вероятность, что эта функция не обеспечивает идеального взаимодействия с пользователем.
Создавая продукты, мы всегда должны стремиться создавать их так, чтобы не было необходимости в документации. Или, по крайней мере, сделайте их так, чтобы чтение руководства было последним средством решения проблем.
Для практических целей, как в прошлом штатный разработчик, я сохранил простой текстовый файл со списком повторяющихся вопросов. Это может быть более сложная настройка для команды, такая как создание проблем GitHub. Мой текстовый файл работал нормально, потому что я был шоу одного человека. Я бы взял за привычку регулярно просматривать список и спрашивать, как я могу улучшить каждый пункт. Некоторые предметы так и не вычеркнули из списка. Однако чаще всего я сначала извлекал важные уроки о создании для конечных пользователей. Я мог видеть вещи, которые имели смысл в моей голове, но сбивали с толку других.
Самые большие улучшения заключались не в поиске решений существующих проблем, а в распознавании проблем в новых продуктах, которые я создавал на основе прошлого опыта.
Со временем большая часть моей документации стала ориентирована на разработчиков. В основном это были учебные пособия по использованию API, хуков и других функций, связанных с разработчиком, – вещей, которые не были представлены через пользовательский интерфейс плагина. Я писал гораздо меньше для конечных пользователей, потому что обновлял проекты на основе их отзывов и вопросов. Да, время от времени я абсолютно терпел неудачу, но я становился все лучше и лучше тех, кто прислушивался к проблемам и вносил изменения, основываясь на том, что пользователи рассказывали мне по-своему.
Когда я говорю, что лучшая документация – это отсутствие документации, я не имею в виду, что вы должны полностью ее пропустить. Я хочу, чтобы вы задали вопрос, зачем нужна документация. Что вы можете сделать, чтобы упростить работу с пользователем? Вы активно отслеживаете вопросы службы поддержки и решаете их в самом продукте?
В процессе разработки мы часто говорим о написании «самодокументирующегося кода». Это способ сказать, что нужно писать код таким образом, чтобы вам не приходилось объяснять его другому разработчику через встроенную документацию. Например, wp_insert_post()функция в WordPress сообщает вам, что ее цель – вставить сообщение. Целью любого программного обеспечения также должно быть создание самодокументирующихся интерфейсов и других элементов, с которыми взаимодействует пользователь. Пользователи должны иметь возможность автоматически понимать назначение кнопки, текстового поля или флажка, не обращаясь к документации.
В следующий раз, когда вы сядете писать новую ориентированную на пользователя часть документации, убедитесь, что вы не используете ее как костыль для поддержки плохого взаимодействия с пользователем.
