суббота, 25 июня 2011 г.

Советы от техподдержки - это НЕ официальная документация продукта

Это перевод Troubleshooting tips are not formal product documentation. Автор: Реймонд Чен.

Microsoft Knowledge Base (база знаний Microsoft) заполнена подсказками по использованию продуктов Microsoft, но вам нужно быть осторожными и понимать область действия написанного.

Вообще говоря, информация из Knowledge Base существует только для разрешения проблем, а не для проектирования дизайна новых программ. Вот почему каждая статья явно перечисляет, к каким версиям ОС или продуктов она относится: нет гарантии, что этот конкретный совет будет работать и для будущих версий ОС или продукта. Это особенно справедливо, если совет говорит про копание во внутренних данных программы, её форматах файлов или реестре. Статьи Knowledge Base предназначены для разрешения ваших проблем; они не являются формальной документацией на продукт. Думайте о ней, как о Microsoft-й версии Experts Exchange (мне всегда было интересно, сколько людей ошибочно читают название этого сайта как "Expert Sex Change").

Статьи Knowledge Base обычно рождаются в технической поддержке продуктов. Кто-то может решить проблему клиента и сказать: "Вы знаете, мне кажется, что другие люди тоже могут встретиться с этой же проблемой. Давайте тогда я задокументирую, как я её решил, чтобы сэкономить время в следующий раз". Они пишут новую статью в Knowledge Base и добавляют её в базу. Иногда (достаточно редко по моему опыту) они передают статью разработчикам продукта для технической рецензии перед публикацией. Иными словами, статьи в Knowledge Base приходят с "уровня обслуживания" ниже формальной документации продукта; совершенно не обязательно, что их одобрили разработчики продукта. Если статья помогла вам исправить проблему - замечательно! Но нет никакой гарантии, что она это сделает и нет гарантии, что это будет работать и в будущем, на следующей версии продукта/ОС. Просто куча IT-шников делятся своим опытом и историями.

Но это объяснение также неверно.

Дело в том, что опубликовать статью в Knowledge Base - это существенно быстрее, чем включить её в формальную документацию, так что разработчики часто "срезают углы" и публикуют часть документации через Knowledge Base, чтобы быстрее доставить информацию клиентам. В результате некоторые статьи Knowledge Base в действительности являются формальной документацией, которая маскируется под советы разрешения проблем.

Иногда статья Knowledge Base проходит через обзор группой разработчиков, вроде статей по использованию rundll32 для отладки апплетов Панели управления и программного запуска Панели управления. Программный способ - это использование программы Control.exe, которая появилась в Windows 3.0. Техника с rundll32 предназначена только для отладочных целей. Если вы используете технику с rundll32 для вашего ПО, то у вас будут проблемы, потому что вы обходите официальную точку входа и используете чёрный вход. Официальная точка входа включает в себя использование хаков обратной совместимости, она знает о именах Панели управления, которые были удалены, и перенаправляет их на их заменители, она знает, куда были перемещены специальные папки Оболочки, и знает, как работать с 64-битными программами, которые запускают 32-битные апплеты (и наоборот). Но если вы вызываете апплет напрямую через rundll32, вы ничего из этого не получаете. Вот почему в статье говорится, что это только для отладки, а не для регулярного использования.

Плохие новости для вас, бедный читатель, заключаются в том, что из текста статьи не следует, на статью какого типа вы смотрите. Это либо (1) совет "как есть" от техподдержки, который может вам помочь решить проблему, либо (2) совет "как есть", который прошёл рецензирование разработчиков и они собираются поддерживать его в дальнейшем, либо же (3) документация на продукт, которая маскируется под совет техподдержки.

Лично я могу распознать разницу между {1,2} и {3} просто по тону статьи и чувства "Боже, они же не собираются в действительности поддерживать это решение вечно?". Может быть, я был изначально рождён с этой способностью (или, быть может, она развилась в начале моей карьеры разработчика программ), потому что, кажется, большинство людей не могут это делать.

Вот вопрос, на который стоит ответить: основывается ли предлагаемое решение на чём-то, что выглядит как побочный эффект, внутренний формат данных, который может быть изменён в будущем? Возникает ли чувство, что это не разработанное изначально решение? Что оно склеено скотчем и сшито белыми нитками?

Мне жаль, что получается такая мешанина, но с сотнями тысяч статей в Knowledge Base, нет никакой возможности пройти и рассортировать такой объём. Вам придётся использовать ваше собственное суждение.

Комментариев нет:

Отправить комментарий

Можно использовать некоторые HTML-теги, например:

<b>Жирный</b>
<i>Курсив</i>
<a href="http://www.example.com/">Ссылка</a>

Вам необязательно регистрироваться для комментирования - для этого просто выберите из списка "Анонимный" (для анонимного комментария) или "Имя/URL" (для указания вашего имени и ссылки на сайт). Все прочие варианты потребуют от вас входа в вашу учётку (поддерживается OpenID).

Пожалуйста, по возможности используйте "Имя/URL" вместо "Анонимный". URL можно просто не указывать.

Ваше сообщение может быть помечено как спам спам-фильтром - не волнуйтесь, оно появится после проверки администратором.