API… Знакомое на слух словосочетание. Что это такое? Кому это надо? И в чем смысл документирования?
API - Application Programming Interfaces – это не что иное, как интерфейсы программирования приложений. В наши дни API вошли в жизнь прочно и навсегда и не всегда заметны пользователю. Тысячи и тысячи API, которые используются людьми каждый день, должный быть общедоступны, просты и удобны в применении.
Следовательно, документирование API требует грамотных и квалифицированных специалистов – технических писателей. Именно они создают тексты, понятные для простого пользователя. Именно API продукта, будь то программное обеспечение или веб-страница, позволяет представить пользователям ту информацию, которая задумана к трансляции.
Вся работа по разработке API проводится аккуратно и внимательно. Необходимо грамотно и пошагово описать условия для пользователя. При этом между кодом и документацией не должно быть разъединения.
Комплект документов API совместно готовит технический писатель со всей командой разработчиков. Для этого привлекается переносимый формат, пригодный для всех текстовых редакторов. Это позволит разработчикам не вникать в работу новых редакторов, а работать в знакомом и комфортном.
Следовательно, документы API возможно писать в текстовых форматах, после чего обработать в генераторе статичных сайтов для создания увлекательных веб-сайтов или документов формата PDF.
Пакет документации API состоит из:
- инструкции по установке и регулированию;
- справочных сведений (с указанием возможных недочетов и имеющихся исключениях);
- действующих и реальных примеров кода и уроков;
- документацию для коммерции и предпринимательства.
Для API необходимо тестирование, которое и покажет возможные недочеты. При этом проводиться тестирование необходимо на разных конфигурациях, чтобы удостовериться в корректности инструкций.
Процесс обновления API должен быть понятным и удобным для пользователей.
И в заключение: любой технический писатель должен работать в команде и быть очень внимательным ко всем деталям.
