Написанное здесь обусловлено тем, что в последние год-два приходилось сталкиваться наверное раз пять с различными проявлениями в отношении пользователей к API и документации в целом. В данном сообщении в основном все базируется на одноименной статье Стивена Кларка, имеющейся в книге «Идеальная разработка ПО», и в е-виде содержимое на находится. Стивен провел более 10 лет работая над совершенствованием API в Microsoft'е, с 1998-го года, с такими инструментами, как Visual Studio.
Удобство API
Сплошь и рядом попадается ситуация, когда проектирование библиотек, API и т.п. происходит как есть, для себя, по каким-то высшим или подсознательным катеогриям, но без какого-либо обращения внимания на пользователей, их разнообразие и решаемые ими задачи. Так получается, что потери reengineering'a с той стороны либо совершенно не волнуют, либо списываются на глупость или неусидчивость пользователей, и более того, идут аргументы вида «а вы используете неправильно, не ходите туда и не делайте так, делайте как мы».
Цитата С. Кларка:
Меня как разработчика, который пользовался Visual Studio до присоединения к группе Visual Studio, используемые инструменты часто раздражали. Параметры компилятора было трудно найти и задать. Настройка путей к библиотекам выглядела громоздкой и неудобной. У продукта было много недостатков из области удобства использования, которые я хотел исправить при поступлении на работу в Microsoft.
Я не хочу сказать, что у меня не было трудностей с API фирмы Microsoft. Напротив, чуть ли не самые серьезные проблемы, с которыми я когда-либо сталкивался, были связаны с пониманием API библиотек MFC. Но в отличие от ситуации с инструментами, в том, что мне не удается разобраться в правильном использовании VFC, я винил только себя. Ни разу я не подумал, что проблема крылась в проектировании API.
Такая реакция на плохо спроктированные API встречается очень часто. Многие разработчики объясняют возникающие трудности своей неопытностью в обращении с API. Будь у них побольше времени, то они бы во всем разобрались. Я много раз слышал, как разработчики говорят, что им просто не хватает ума для освоения API.
Таким образом, документация и API могут быть неудобными и плохо спроектированными. Если на это не обращать внимания, то именно так и произойдет, а при более внимательном рассмотрении можно даже понять почему.
Работа с API не представляет собой работу со всем API целиком
В повседневной работе лишь немногие работают сразу со всем API. Как правило, интересы ограничиваются только той задачей, которую пытаются решить. То есть, необходимо сосредотачиваться на том, для чего предназначены API, а не на том, что оно собой представляет.
Вторым моментом является то, что все API редко кто понимает или даже пытается понять, так как это большой объем информации. Используется какой-то участок фронта для какой-то задачи в течение какого-то времени. И все. Но с другой стороны баррикад почему-то считается правильным заставлять других учить авторские предрассудки и геометрию граблей архитектуры. Зато удобно и есть кого обвинить.
Аналогичную ситуацию наблюдаю с документацией. Вместо решения конкретных задач и ориентации на пользователя пишется большой талмуд обо всем, а на все вопросы идет ответ — идите читайте нашу прозу и медитируйте над тем, что мы тут натворили. Это как если бы вы пришли на почту с вопросом, когда приходит почтальон, а в ответ вам нужно было бы изучить архитектуру того, как работает организация, кто за что отвечает, откуда берет план и график обхода с точной траекторией.
Таким образом, в редких случаях идет работа пользователя целиком со всем, что есть. А для пользователя есть задачи, которые ему нужно решать. И в круг этих задач не входит постижение некого дао.
Разные пользователи
Одним из результатов исследований было то, что пользователи разные, в том плане что они по разному работают с API и её документацией. И вписаться сразу в каждый мир и угодить всем мягко говоря, сложно.
Три типа пользователей из статьи:
- Коньюктурщики (оппортунисты)
- Для этой категории характерна привычка к быстрому экспериментированию, задачно-ориентированный подход и широкое использование высокоуровневых конкретных компонентов.
- Прагматики
- Деятельность разработчиков этой категории ориентиирована на программный код. Они пользуются инструментами, которые способствуют улучшению правильности и надежности написаного кода.
- Педанты
- Для педантов характерен «безопасный подход» к разработке; они считают, что для использования любой технологии необходимо сначала глубоко разобраться в ней.
Первые работают на высоком уровне (абстракции), вторые и третьи на более низком. Педанты любят гибкость примитивов (например отображение файла в память и полный контроль). Прагматики склоняются к факторизированным компонентам, т.е. агрегатные компоненты для коньюктурщиков (чтение текстового файла и работа со строкой), но с выделенными типовыми режимами работы (бинарный файл, аналогичный тому, как на диске). Соответственно, для каждых из них имеется разное представление об удобстве API.
В данном случае одно из решений — сценарно-ориентированное проектирование. Так понял, что в данном случае это когда на сооветствющем уровне абстракции готовятся API и документация для соответствующего типа пользователя.
Таким образом, пользователи разные, и что хорошо одному, может быть плохо другому, и наобормот.
Архитектура API и интерфейс пользователю
Архитектура это одно, и она не обязана быть известной пользователю. Более того, чаще всего она не помогает в решении задачи. Для пользователя намного важным является интерфейс и предоставляемая функциональность, позволяющая решать его задачи. И если описывать архитектуру, то получится много, и не для пользователя.
