Как писать документацию к интерфейсам

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

#документация #интерфейсы #технический писатель

Три главных предмета в фокусе внимания

Потребитель документации

Кому она нужна? Следующему дизайнеру, разработчику, QA, аналитику, пользователю?
Интеграция с результатом

Близость документации к тому, что вы описываете. Документация должна лежать рядышком с макетами.
Сама необходимость документации

Усилий много, а толку может и не быть. Часто макетов достаточно, они сами по себе документация.

5 советов,
как делать хорошо

Не делайте
Скорее всего она никому не нужна. Очень часто желание сделать документацию — это рефлекс. Да, можно сделать. Да, мы тоже делали. Нет, это почти никогда не нужно. Самые разные команды разработки прекрасно обходились без документации к нашим интерфейсам и сами просили нас не тратить на нее время.
Наведите порядок в макетах
Хорошо структурированные макеты и внятные комментарии избавляют от необходимости дополнительно документировать дизайн.
Смиритесь с тем, что документация меняется
Синхронизация документов с макетами — дикая проблема. Лучше даже не пытаться.
Подходите к докментации, как к интерфейсу
Например, если разработчкам нужна документация, чтобы начать работать, лучше оформить ее как набор задач в бэклоге, а не как единый документ. Если нужна не столько документация, сколько презентация — ее и делай.
Привлеките технического писателя
Если работа с буквами неизбежна (например, это требование договора), то пусть ее делает специально обученный человек. Это не менеджер и не дизайнер.