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

В частности, один из докладов на конференции OSCON был посвящён этой теме. Бен Холл (проекты Katacoda и Ocelot Uproar) изложил свою точку зрения на важнейший для всего сообщества вопрос.

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

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

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

Эксперт приводит пример, который хорошо знаком всем, кто изучал информатику — знаменитую программу Hello World. Она очень проста, поэтому люди не «опускают руки» на раннем этапе обучения. Документация должна строится по точно такому же принципу, ориентируясь на реальные поведенческие нормы пользователей, а не умозрительные представления разработчиков.

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

Исследование

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

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

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

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

Принятие решения

Если первый шаг пройден посетителем успешно, то у проекта появился потенциальный пользователь, готовый потратить некоторое время на более обстоятельное изучение решения. Правда, обольщаться пока рано — Холл считает, что если через девять минут его интерес не окрепнет, то мотивация исчезнет.

Документацию второго шага часто принято называть «Getting Started». Возможно, есть резон включить в неё небольшие фрагменты кода — не исключено, что посетитель проявит интерес не только к использованию приложения, но и решит принять участие в разработке.

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

Начало работы

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

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

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

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

Использование

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

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

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

Ссылки

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

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