Как писать документацию к интерфейсам
Желание сделать документацию к интерфейсам — рефлексивное, но чаще всего бессмысленное. Важно понять, зачем и кому эта документация нужна и как обойтись без нее. Почти наверняка аккуратно структурированных макетов будет достаточно. А если нет, то лучше всего поручить дело техническому писателю.
#документация
#интерфейсы
#технический писатель
Три главных предмета в фокусе внимания
1
Потребитель документации
Кому она нужна? Следующему дизайнеру, разработчику, QA, аналитику, пользователю?
2
Интеграция с результатом
Близость документации к тому, что вы описываете. Документация должна лежать рядышком с макетами.
3
Сама необходимость документации
Усилий много, а толку может и не быть. Часто макетов достаточно, они сами по себе документация.
Например
Хороший образец
Пример «самодокументируемого» проекта, где без лишних букв понятно, что как работает. Приложение для проверки и подписи документов
Так делать не надо
Попытка держать полную и синхронизированную с изменяющимся прототипом текстовую документацию, просто чтобы было. Это невозможно.
Инструменты
Figma
Выжмите из нее все. Дерево фреймов, dev-mode, секции, комментарии, стрелочки и подписи.
Jira
Часто макеты сразу превращаются в таски, минуя этап документирования.
Любая википодобная система
Например, Notion. Чтобы сразу писать задать структуру и перелинковать разделы между собой.
Технический писатель
Если не можете привлечь, хотя бы проконсультируйтесь
Написание документации — отличный повод попрактиковаться в делегировании.
Евгений Романовский, руководитель проектного офиса «Собаки Павловой»
5 советов,
как делать
хорошо
1
Не делайте
Скорее всего она никому не нужна. Очень часто желание сделать документацию — это рефлекс. Да, можно сделать. Да, мы тоже делали. Нет, это почти никогда не нужно. Самые разные команды разработки прекрасно обходились без документации к нашим интерфейсам и сами просили нас не тратить на нее время.
2
Наведите порядок в макетах
Хорошо структурированные макеты и внятные комментарии избавляют от необходимости дополнительно документировать дизайн.
3
Смиритесь с тем, что документация меняется
Синхронизация документов с макетами — дикая проблема. Лучше даже не пытаться.
4
Подходите к докментации, как к интерфейсу
Например, если разработчкам нужна документация, чтобы начать работать, лучше оформить ее как набор задач в бэклоге, а не как единый документ. Если нужна не столько документация, сколько презентация — ее и делай.
5
Привлеките технического писателя
Если работа с буквами неизбежна (например, это требование договора), то пусть ее делает специально обученный человек. Это не менеджер и не дизайнер.