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

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

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

Представьте, что вам нужно выполнить задание по математике в LaTeX, и кто-то советует прочитать книгу «TeX: The Program». Хотя это отличная книга, ваша цель — получить PDF с правильно оформленным домашним заданием, а не читать роман. Подавляющее большинство людей, посещающих вашу документацию, приходят не для того, чтобы узнать больше о вашем увлекательном продукте. Они хотят понять, как выполнить конкретную задачу: написать библиотеку для двухфакторной аутентификации или разобраться, как принимать звонки от «фейковой подруги».

Не стоит ожидать, что пользователи действительно будут **читать** вашу документацию. Многие просто скопируют содержимое блока кода в текстовый файл или командную строку и будут ждать, что оно заработает, не читая никаких пояснений. Вы не можете предполагать, что у пользователей есть какой-либо контекст, кроме того, что вы указали в примере кода и, возможно, одной-двух фраз выше или ниже. Давайте рассмотрим пример на основе старого фрагмента из библиотеки twilio-python API.

«`

# Как сделать звонок

client = TwilioRestClient()

calls = client.calls.list(statsus=Call.IN_PROGRESS)

call = client.calls.create(to=»9991231234″, from_=»9991231234″,

url=»http://foo.com/call.xml»)

«`

Это вызовет ряд проблем для разработчика, впервые использующего Twilio.

Их скрипт не сработает, если они не добавят в начало файла строку:

`from twilio.rest import TwilioRestClient`

Инициализация TwilioRestClient без параметров означает, что конструктор будет искать в окружении пользователя переменные `TWILIO_ACCOUNT_SID` и `TWILIO_AUTH_TOKEN`. Документация по этим параметрам находится в другом месте. Лучше быть явным:

«`

ACCOUNT_SID = «ACXXXXXXXX»

AUTH_TOKEN = «dddddddddddd»

client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)

«`

Аргумент метода `list`, `statsus`, написан с ошибкой, поэтому параметр не будет передан корректно. Если пользователь не знает о TwiML и не изменит параметр `url`, то первое, что он услышит при подключении звонка, — это сообщение: «Произошла ошибка приложения». В этом сообщении нет контекста, чтобы узнать о TwiML или понять ошибку. Вместо ссылки на несуществующий URL используйте что-то, что действительно демонстрирует работу вашего продукта:

«`

call = client.calls.create(to=»9991231234″, from_=»9991231234″,

url=»http://demo.twilio.com/welcome/»)

«`

Теперь наш пример стал более надежным и содержит необходимый контекст:

«`

from twilio.rest import TwilioRestClient

# Как сделать звонок

ACCOUNT_SID = «ACXXXXXXXXXXX»

AUTH_TOKEN = «dddddddddddd»

client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)

calls = client.calls.list(status=Call.IN_PROGRESS)

call = client.calls.create(to=»9991231234″, from_=»9991231234″,

url=»http://demo.twilio.com/welcome/»)

«`

Когда что-то ломается, важно сообщить пользователям, что именно пошло не так и как это исправить. Некоторые вещи вы не можете контролировать, например, когда пользователь запускает `pip install twilio` и получает ошибку `-bash: pip: command not found`.

Это сообщение не дает подсказки, как исправить проблему, и вы не можете его изменить. Но вы должны предвидеть и предоставлять явные сообщения об ошибках там, где можете контролировать вывод. Продолжая пример выше, вот как раньше выглядело сообщение об ошибке:

«`

>>> from twilio.rest import TwilioRestClient

>>> client = TwilioRestClient()

Traceback (most recent call last):

File ««, line 1, in

File «/Library/Python/2.6/site-packages/twilio/rest/__init__.py», line 110, in __init__

twilio.TwilioException:

Twilio не смог найти учетные данные вашего аккаунта.

«`

Это не объясняет, где именно нужно указать учетные данные. Лучше так:

«`

>>> from twilio.rest import TwilioRestClient

>>> client = TwilioRestClient()

Traceback (most recent call last):

File ««, line 1, in

File «/Library/Python/2.6/site-packages/twilio/rest/__init__.py», line 110, in __init__

twilio.TwilioException:

Twilio не смог найти учетные данные вашего аккаунта. Передайте их в конструктор TwilioRestClient следующим образом:

client = TwilioRestClient(account=’ACCOUNTS_SID’, token=’AUTH_TOKEN’)

Или добавьте учетные данные в переменные окружения. В macOS или Linux добавьте следующее в файл .bashrc:

TWILIO_ACCOUNT_SID=AC3813535560204085626521

TWILIO_AUTH_TOKEN=2flnf5tdp7so0lmfdu3d7wod

Замените значения Account SID и токена на значения из вашего аккаунта Twilio по адресу https://www.twilio.com/user/account.

«`

Ваши сообщения об ошибках всегда должны объяснять, как решить возникшую проблему. Иначе они приведут к обращениям в поддержку (что увеличит расходы) и/или разочарованию (что приведет к потере дохода).

Более 50% посетителей документации Twilio приходят напрямую из Google, и, вероятно, ваша документация имеет схожий показатель. Это имеет несколько интересных последствий.

Во-первых, вам нужно думать о SEO для всего, что вы пишете. В частности, убедитесь, что:

— страницы документации содержат ровно один тег `