Писатель API — это технический писатель , который пишет документы, описывающие интерфейс прикладного программирования (API). Основная аудитория — программисты, разработчики, системные архитекторы и системные дизайнеры.
API — это библиотека , состоящая из интерфейсов, функций, классов , структур, перечислений и т. д. для создания программного приложения. Она используется разработчиками для взаимодействия с программным обеспечением и его расширения. API для данного языка программирования или системы может состоять из системно-определенных и пользовательских конструкций. По мере увеличения количества и сложности этих конструкций разработчикам становится очень утомительно помнить все функции и определенные параметры. Следовательно, авторы API играют ключевую роль в создании программных приложений.
Из-за технической сути, писатели API должны понимать исходный код приложения в достаточной степени, чтобы извлекать информацию, необходимую для документов API. Писатели API часто используют инструменты, которые извлекают программную документацию , размещенную программистами в исходном коде, структурированным образом, сохраняя связи между комментариями и программными конструкциями, которые они документируют.
Авторы API также должны понимать программный продукт и документировать новые функции или изменения как часть нового выпуска программного обеспечения. График выпусков программного обеспечения варьируется от организации к организации. Авторы API должны хорошо понимать жизненный цикл программного обеспечения и интегрироваться в жизненный цикл разработки систем (SDLC).
Авторы API в Соединенных Штатах обычно следуют Чикагскому руководству по стилю в отношении грамматики и пунктуации . [ требуется ссылка ]
Авторы API обычно обладают сочетанием навыков программирования и языка; многие авторы API имеют опыт программирования или технического письма .
Опытные разработчики API/ комплектов для разработки программного обеспечения (SDK) могут легко стать программистами .
Процесс написания API обычно делится на анализ и понимание исходного кода , планирование, написание и рецензирование. Часто бывает так, что этапы анализа, планирования и написания не происходят строго линейно.
Критерии написания и оценки различаются в разных организациях. Некоторые из наиболее эффективных документов API написаны теми, кто в достаточной степени способен понимать работу конкретного приложения, чтобы они могли связать программное обеспечение с пользователями или различные конструкции компонентов с общей целью программы. Авторы API могут также отвечать за создание документации для конечного пользователя продукта.
Хотя справочная документация может быть создана автоматически для обеспечения полноты, документация, которая поможет разработчикам начать работу, должна быть написана профессиональным писателем API и проверена экспертами в данной области. [1] Это помогает гарантировать, что разработчики понимают ключевые концепции и могут быстро приступить к работе.
Разработчики API создают документы, которые включают в себя: