Документирование API, как определить подход, который устроит всех.

1. Существует множество подходов к документированию API. Определить подход к документированию сложно, так как с одной стороны есть потребность к полному и подробному описанию, с другой стороны такое описание не будет иметь практической ценности из за своей избыточности для отдельно взятых участников процесса разработки.

2. При определении подхода к описанию API нужно учитывать факторы:

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

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

c. Стандарты принятые в компании. В больших компаниях уже существуют лучшие практики описания документации.

3. Для определения подхода к документированию можно использовать чек листы. Чек лист помогает выбрать подход и инструменты для описания API учитывая потребности всех участников процесса разработки. Чек лист помогает стандартизировать документацию по продукту и повысить её качество.