Типы документации

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

Справка → База Знаний → Помощь

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

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

Помощь — Справка или База Знаний с окошком диалога. В Помощи оказывают помощь — поэтому называть так стоит только тот портал, через который можно общаться с поддержкой.

API

Здесь всё не так однозначно. Первое, на что стоит обратить внимание в документации API — у неё минимум две аудитории. Разработчики, которые будут использовать методы и лица, принимающие решение об использовании API для своих задач. Поэтому в API должно быть две части: что это, как оно работает, какой профит от его внедрения; и сами методы с примерами кода.

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

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

Документы цикла разработки