Большинство разработчиков ПО с открытым исходным кодом в основном задумываются о качестве программ, которые они проектируют, часто забывая, насколько важно иметь качественную документацию. Никто не говорит о том, какая крутая инструкция у проекта или какой подробный мануал, но все же документация оказывает большое влияние на успех проекта. Без хорошей сопроводительной документации, пользователи либо не смогут в полной мере раскрыть весь потенциал продукта, либо, что еще хуже, даже не смогут работать с ним. Если все сложится удачно, довольные пользователи будут активно распространять новости о вашем проекте. Охотнее всего они будут это делать после того, как смогут понять программу и разобраться в ней. Помочь им в этом обязана документация, предоставляемая вместе с программным обеспечением.
Тем не менее, слишком многие проекты с открытым кодом снабжены лишь довольно скудной справочной информацией. Есть несколько причин, влияющих на качество документации.
Ниже я привел 13 замечаний, встречающихся у целого ряда проектов. На самом деле их гораздо больше. Здесь перечислены самые грубые, по моему мнению, ошибки. Каждый проект, который попадался мне на глаза, имел по крайней мере 2 или 3 проблемы из этой статьи. Посмотрите, под какие пункты попадает ваше любимое программное обеспечение в независимости от того, кто вы — пользователь или разработчик. Подумайте, что бы вы лично исправили.
1. Нет нормального файла README или введения
Первое впечатление о вашем проекте пользователи получают из файла README. Если проект размещен на сервисе GitHub, README автоматически отображается на главной странице проекта. Если вы составите файл неправильно, то пользователи, возможно, вообще никогда его и не увидят. А ведь вы должны приковать внимание читателя и побудить его продолжить изучать ваш проект.
README должен давать ответы, по крайней мере, на следующие вопросы:
- Что делает проект?
- На кого рассчитан проект?
- На каком оборудовании или какой платформе он работает?
- Какие зависимости используются? (например, «Требуется Python 2.6 и LibXML»)
- Как установить проект?
Все это должно быть написано с расчетом на тех, кто никогда ничего раньше не слышал о вашем проекте и никогда даже не сталкивался с чем-то подобным. Если у вас есть модуль, который вычисляет расстояние Левенштейна, не думайте, что все, кто читает ваш README, знает, что это такое. Объясните, что расстояние Левенштейна используется для сравнения различий между строками и дайте ссылку на более подробное объяснение для тех, кто хочет изучить тему более подробно.
Еще совет: не рассказывайте о своем проекте, путем сравнения его с другим. Например, «NumberDoodle это как BongoCalc, но только лучше!» Это не поможет пользователям, которые никогда не слышали о BongoCalc.
2. Отсутствие документации в интернете
Я не видел результатов исследования, но держу пари, что 90% людей ищут документацию с помощью поисковых систем. Поэтому мануал по вашему проекту должен быть в обязательном порядке представлен в сети. Лично мне было бы стыдно, если бы мой проект — ack — не получил должного уровня поддержки.
Не стоит пренебрегать такой крупной площадкой как интернет. Подавляющее большинство пользователей будут искать документацию по вашей программе именно здесь. Мое предположение прежде всего основывается на собственном опыте: если я захочу узнать, как работает инструмент командной строки, то я посмотрю это на веб-сайте.
Как эта проблема привлекла мое внимание? Да очень просто. Пользователи постоянно у меня что-то спрашивали, хотя на сайте уже давно существовал раздел с ответами на часто задаваемые вопросы (FAQ). Меня бесило, что они игнорировали этот раздел. Оказалось, они искали на сайте, но ответов на свои вопросы попросту не находили. Это и привело к массовому наплыву писем на почту. Я, близкий к проекту, как никто другой, никогда не пользовался разделом FAQ, поэтому и не заметил отсутствия большинства актуальных тем. Многие попадают в эту ловушку: разработчик забывает поставить себя на место пользователя.
3. Документация есть только в интернете
Обратной стороной этой проблемы является наличие документации только в интернете. Некоторые разработчики не считают нужным размещать инструкции к проектам в сети или выкладывают некачественную документацию.
Поисковая система Solr, например, имеет отличную Вики, в которой представлена полная документация по проекту. К сожалению, документация, которую предлагается скачать, занимает 2200 страниц. Полезная информация для конечного пользователя умещается всего лишь на одной странице.
Язык PHP поставляется отдельно от документации. Если вам она потребуется, то для скачивания вы должны перейти на отдельную страницу. Хуже того, скачать можно только основные разделы помощи, без полезных комментариев пользователей (см. пункт 10, ниже) и подаются они не в таком же простом формате, в котором представлены в интернете.
Не привязывайте пользователей к обязательному наличию интернета. Для этого существует автономный режим. Я и сам два раза за последние несколько месяцев открывал мануал по Solr, когда охотился за информацией по решению сложной проблемы.
Одним из таких проектов, в котором реализована полноценная автономная поддержка, является Perl и его репозиторий CPAN. Документация для каждого модуля представлена по любому из адресов search.cpan.org или metacpan.org в удобном для чтения формате с гиперссылками. Для удобства работы в оффлайн-режиме документация по каждому модулю встроена в сам код, а когда модуль установлен на компьютере пользователя, локальная документация создается в виде отдельных страниц. Пользователи также могут использовать конструкцию `perldoc Module::Name`, чтобы получить мануал из оболочки. Документация в режиме онлайн или оффлайн — на ваш выбор.
4. Документация не устанавливается вместе с пакетом
Эта проблема, как правило, является ошибкой создателей сборки, а не авторов самого проекта. Например, в Ubuntu Linux, документация по языку Perl представляет собой дополнительный пакет от создателей самого языка. Пользователь должен знать, устанавливается документация вместе с пакетом или нет.
5. Отсутствие скриншотов
Нет лучшего способа привлечь внимание потенциальных пользователей или проиллюстрировать работу программы, чем снабдить мануал скриншотами. Один скриншот способен заменить тысячу слов. Использование картинок важно и потому, что трудно заинтересовать пользователя статьей в несколько тысяч символов, не подкрепив ее наглядными изображениями.
Скриншоты также неоценимы для пользователей, которые, пытаясь разобраться в работе программы, следуют инструкции. Скриншот помогает пользователю визуально сравнить свои результаты с результатами, описанными в мануале. Если пользователь допустил ошибку, он обращает внимание на нужный слайд и исправляет ее.
Все чаще разработчики для большего удобства размещают на сайте проекта обзорные видеоролики, в которых процесс разбирается детально с демонстрацией множества возможностей. Например, проект Plone имеет целый сайт, посвященный видеоурокам. Тем не менее, видеозапись не стоит ставить вместо скриншота. Пользователь хочет быстро увидеть, как будет выглядеть работа программы, не прибегая к перемотке видеозаписи. К тому же видео также не появляется в поиске картинок Google в отличие от скриншотов.
6. Отсутствие примеров
Для проектов, ориентированных на программирование, аналогом скриншота выступают примеры работы программы. Эти примеры не должны быть абстрактными, их цель — решать определенную задачу. Не создавайте одноразовые примеры, типа «Hello, World» и lorum ipsum — их полно. Потратьте время на то, чтобы создать подходящий пример, исходя из того, для каких целей было разработано программное обеспечение.
Это немного напоминает школьный урок. В первую очередь объясните пользователю, чему вы его учите.
Скажем, я написал модуль веб-робота, и я объясняю метод follow_link. Я мог бы показать метод определения на следующем примере:
$mech->follow_link( text_regex => $regex_object, n => $link_index );Но посмотрите, как все становится более очевидным при добавлении некоторых изменений.
# Обратите внимание на 2-ую ссылку для строки «download»
$mech->follow_link( text_regex => qr/download/, n => 2 );Абстрактные имена переменных regex_object $ и $ link_index теперь укрепились в сознании читателя.
Конечно, ваши примеры не должны быть короткими фрагментами кода в две строчки. Так выразился Rich Bowen о проекте Apache: «Один правильный, функциональный, проверенный пример с подробными комментариями — это ваш козырь».
Покажите все, на что способны. Заполняйте свободное пространство. Сделайте специальный раздел в документации для примеров или даже поваренную книгу. Попросите пользователей отправить вам куски рабочего кода и опубликуйте лучшие из них.
7. Недостаточное количество ссылок
У вас есть гиперссылки. Используйте их.
Объясняя какое-либо явление, не ленитесь ставить ссылки на статьи по теме. Не думайте, что пользователь знает все. Возможно, он упустил какой-то момент. Не просто укажите, что эта часть кода манипулирует этим объектом. Остановитесь на кратком объяснении объекта и дайте ссылку его на развернутое описание. А лучше всего сделайте и то, и другое!
8. Не забывайте про новых пользователей
Часто случается, что при написании документации автор программного обеспечения опирается только на свою точку зрения. Поэтому, прежде чем понять о чем идет речь, новичок должен изучить вступительный материал.
Введение должно быть на отдельной странице документации, желательно с примерами, которые позволяют новичку войти в курс дела при работе с новым программным обеспечением. Представьте, что к вам в руки попадает неизвестное программное обеспечение, вы начинаете разбираться в нем и выдаете что-нибудь классное. Сделайте так, чтобы новичок поскорее оказался на вашем месте.
Например, в мануале к графическому пакету можно сделать серию скриншотов, которые показывают, как добавить данные в файл или создать график. В мануале к библиотеке можно показать несколько примеров вызова библиотеки, а затем показать результаты вывода. Не усложняйте документацию, пусть она будет простой. В тексте должны быть краткие описания, а также ссылки на более подробную информацию.
Отдельный документ для вводного материала дает пользователю возможность быстро понять суть программного обеспечения.
9. Нет обратной связи с пользователем
Владельцы проекта должны прислушиваться к мнению юзеров. Самое главное в этом деле — принимать пожелания и предложения от активной части пользовательской аудитории. Когда пользователь обращается к вам с просьбой типа: «Помогите мне разобраться с программой, так как я не могу найти информацию о том, как установить базу данных драйверов», отнеситесь к этому сообщению всерьез. Отвечайте на каждое сообщение пользователей.
Важно обращать внимание на то, чем вызвана эта проблема. Если люди часто сталкиваются с одной и той же проблемой, например, «как выполнять массовые обновления базы данных?», в первую очередь, нужно добавить вопрос в FAQ (у вас есть FAQ, не так ли?). Или же часто возникающие вопросы могут быть признаком того, что данный раздел документации не написан достаточно ясно. Бывает и такое, что из введения пользователи не могут перейти в соответствующий раздел руководства.
Помимо того, что вы помогаете большему количеству людей узнать, насколько полезен ваш проект, вы также обеспечиваете поддержку сообщества, сформировавшегося вокруг проекта. Если ваш список рассылки, форум или IRC-канал наполнен людьми, которые задают одни и те же «тупые» (или не очень тупые) вопросы, значит, пришло время обновить FAQ-раздел. Это существенно облегчит вашу жизнь и освободит время для полезных дел.
По возможности следите за вопросами пользователей на других форумах. Например, на сайте StackOverflow, посвященном программированию, регулярно публикуются актуальные вопросы и ответы на них. Настройте предупреждения Google Alert для вашего проекта, и вы будете постоянно проинформированы о текущем состоянии дел.
10. Нет поддержки пользовательских примечаний
Если ваш проект имеет достаточно большую базу пользователей, возможно, имеет смысл интегрировать комментарии прямо в документацию. Мне понравилось, как данная возможность реализована в языке PHP. На каждой странице руководства зарегистрированные пользователи могут оставлять комментарии. Это помогает прояснить ситуацию вокруг какой-нибудь темы или добавить примеры, которых нет в основной части документации. Команда PHP также предоставляет читателям возможность выбрать, в каком режиме просматривать документацию — с комментариями или без них.
Эта функция, конечно, полезна, но требует постоянной поддержки. Вы должны следить за комментариями и не допускать замусоривания. Например, страница руководства PHP о том, как вызвать PHP из командной строки, включает в себя 43 комментария от пользователей. Причем самый первый был опубликован в 2001 году. Лишние комментарии должны архивироваться или удаляться, а самые важные нужно включить в основную документацию.
Создание Вики тоже будет хорошим решением. Однако если пользователь не имеет возможности скачать всю Вики целым архивом (см. пункт 3 выше), то вы обрекаете его на зависимость от подключения к интернету.
11. Пользователь не может увидеть, что делает программа, не установив ее
Как минимум, каждый программный продукт нуждается в списке возможностей и скриншотах, чтобы наглядно объяснить пользователю, почему он должен выбрать данное ПО. Сделайте так, чтобы пользователь, который находится в поиске необходимого ПО, заинтересовался вашим проектом. Для этого в доступной форме объясните и покажите ему, на что он потратит свое время, скачав и установив ваше приложение.
Изображения представляют собой отличный инструмент для демонстрации возможностей программы. Ваш проект обязан иметь страницу со скриншотами, которая показывает реальные примеры используемого инструмента (см. пункт № 5 выше). Если проект базируется на коде, например, библиотека, то в обязательном порядке должна быть страница с примерами.
12. Упор на технологии при составлении документации
Слишком часто авторы программного обеспечения используют автоматизированные системы, чтобы облегчить себе работу. Они забывают, что здесь не обойтись без человеческого подхода. Автоматизированная система помогает упростить некоторые вещи, но это не отменяет потребности в документации, написанной человеческим понятным языком.
Худшим случаем автоматизации являются логи изменений, которые являются ничем иным, как списком версий, но без вменяемых объяснений. В изменениях должны быть перечислены новые функции, исправленные ошибки и возможные несовместимости. Логи изменений предназначены в основном для разработчиков. Их легко генерировать, но это не то, что нужно пользователям.
Взгляните на эту страницу из руководства по Solarium, PHP-интерфейс к поисковому движку Solr. Во-первых, дислеймер занимает верхнюю половину экрана, не давая информации для читателя. Во-вторых, на странице нет никакого описания, кроме списка функций. «METHOD_FC» означает «Facet method fc». Но что такое FC? Нет никакого объяснения по поводу различных фасетных методов, ни ссылок, из которых можно почерпнуть информацию. Автоматически сгенерированные страницы выглядят хорошо, но они не могут рассматриваться в качестве вменяемого руководства.
13. Высокомерие и враждебность по отношению к пользователю
Не посылайте своих пользователей на четыре волшебные буквы RTFM (Read the Freaking Manual) — это не приемлемо.
Этим самым вы заявляете, что все проблемы происходят по вине пользователя. Это все равно, что предположить — «им просто лень читать», о чем вы не можете знать наверняка. Большинство из нас сталкивались с таким явлением. Зачем же вам проявлять негативное отношение к людям, которые хотят использовать ваше программное обеспечение.
Даже если пользователи могли бы найти свои ответы в документации, но почему-то этого не сделали, глупо валить все на пользователя. Может быть, ваша документация плохо составлена и нужную информацию трудно найти. Возможно, вам нужно улучшить раздел «Начало работы» (пункт № 8 выше), в котором объясняется для чего предназначено ПО. Может быть, следует продублировать важную информацию в других частях руководства, чтобы заострить на этом внимание пользователя. Может быть, вы не ясно даете понять читателю, где искать необходимую информацию.
Вы же в курсе, что новые пользователи могут подключиться к вашему проекту, вообще ничего не зная. Руководство пользователя, составленное вашей командой, должно сделать все возможное, чтобы дать исчерпывающие ответы на все его вопросы.
Заключение
Я уверен, что вам не раз приходилось сталкиваться со многими из вышеперечисленных проблем с документацией. Дайте нам знать о проблемах, которые беспокоят вас в комментариях к этому посту. Я не хочу указывать пальцем на конкретные проекты, так как практически каждое ПО с открытым кодом имеет некоторые проблемы разной степени тяжести.
Прежде всего, я надеюсь, при обнаружении проблем в своей документации, вы займетесь их устранением. Кстати, улучшение документации является идеальным способом для привлечения новых пользователей. Меня часто спрашивают: «с чего мне начать работать с открытым исходным кодом?». Я бы порекомендовал начинать с улучшения документации. Это отличный способ для старта.
Сделайте руководство удобным как для новичков, так и продвинутых пользователей. Создайте список задач, по возможности в вашей системе отслеживания ошибок, для того чтобы понимать, что нужно исправить. Будьте конкретны в своих потребностях. Не просто укажите: «нам нужно больше примеров», а создайте конкретную задачу, например: «добавить пример, как решить задачу X», «добавить скриншоты к процессу Z», или «Ддобавить информацию о зависимостях в README». Многие хотят исправить ситуацию, но не знают, с чего стоит начинать.
Руководство пользователя — это не главная часть проекта с открытым кодом, и для большинства из нас составление документации не самое веселое занятие. Но без хорошей документации пользователи не смогут взаимодействовать с вашим ПО и, соответственно, поддерживать в нем жизнь.