7 авг. 2010 г.

О дизайне в документации разработчика

Долго не мог понять в чем проблема, но только что разобрался и тороплюсь доложить вам. Заметил, что читая документацию в MSDN’е на душе становится как-то хорошо и спокойно, а когда читаю в doxygen’е, то как-то подташнивает.

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

Так вот, если меня интересует какой-либо класс из библиотеки .NET, то в MSDN’е описание выглядит так:

msdn

Здесь четко видно: секция «конструкторы» — один метод, секция «методы» — пять. Плотность подачи информации равна шести единицам. Давайте посмотрим на документацию в дефолтовом стиле doxygen’а:

doxygen

Секции всё также видны, но так легко считать отдельные методы уже не получается. Визуально толстые синие ссылки доминируют над декларациями методов, и отвлекают внимание. Более того, на одном экране мы видим описание только трёх методов. Значит условная плотность равна трём.

Обратите внимание, как doxygen заботливо тип «unsigned» сделал ссылкой. Если вы забудете, что такое unsigned, то вы всегда сможете пройти по ссылке и узнать.

Важная часть документации — это не только описание, но и примеры исходного кода. В MSDN’е мы видим исходники в таком оформлении:

msdn_source

Раз, два, три, четыре — и всё. Четыре цвета. Исходный код в doxygen’е выглядит так:

doxygen_source

Здесь же мы видим такие классы подсветки: 1) директивы; 2) ссылки; 3) ключевые слова раз; 4) ключевые слова два; 5) комментарии; 6) встроенные типы; 7) идентификаторы, пунктуация. Итого семь разных цветов. Понятно, что подкраска — это дело вкуса, но если пользователь и так знает, что на любой идентификатор можно кликнуть и перейти в место определения, то зачем лишний раз выделять ссылки синим цветом?

Ну и на последок уменьшенная в пять раз collaboration diagram из doxygen’а. Реально кто-то будет ей пользоваться будучи в реальном размере (3600 на 1500 пикселей, смотреть оригинал)?

collaboration_750px

В комментариях приветствуются ссылки на мануалы и личный опыт ведения документации, настройки doxygen’а и прочее.

12 комментариев:

  1. Во-первых, я что-то не уверен, что в MSDN документация генерилась автоматом прямо из кода.

    Во-вторых, в doxygen ты можешь настраивать стили так, как тебе удобно.

    Но замечания вообще верные, согласен.

    ОтветитьУдалить
  2. Давай различать две вещи: а) как оно генерировалось; и б) как оно выглядит. Очевидно, что в MSDN'е оно выглядит лучше. (Кстати, в 2008 и 2010 встроен XML-генератор документации. Поэтому MSDN может быть и сгенерирован.)

    И второе: почему нельзя сразу сделать красиво, чтобы не мучить пользователей? Зачем нужно лезть, вникать во все эти стили и настройки, тратить время на настройку и перегенерацию, чтобы сделать нормальную документацию?

    ОтветитьУдалить
  3. Зачем «давай различать»? Эти вещи взаимосвязаны хотя бы потому, что никакая утилита не сможет разделить код по каким-то логическим признакам так, как это может сделать человек.

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

    P.S. Генератор документации из xml появился вроде ещё в 2005 студии. Кстати, doxygen поддерживает этот формат тоже.

    ОтветитьУдалить
  4. Что-то я перестал тебя понимать. Логические признаки - это метакомментарии. Всё, что нужно было сделать: это в левой колонке таблицы написать декларацию метода, а в правой колонке описание. Какой утилите это не сможет?

    ОтветитьУдалить
  5. Мне кажется, что сравниваются немного разные вещи. MSDN - это всё-таки не утилита, для создания документации, коим является doxygen. Думаю, что MSDN тоже создается каким-нить MC аналогом doxygen'a. В котором тоже заботливые люди настраивали стили, шрифты, цвета.

    Никогда не пользовался doxygen, но насколько слышал, там есть возможность кастомизиворать многое.

    ОтветитьУдалить
  6. Ребяты, ну вы, это...

    Не сравниваются утилиты по генерации. Сравнивается подача. И то, и другое является онлайн-документацией к библиотекам классов. И там, и там одинаковые технологии HTML, CSS, JavaScript. Значит цели и возможности у них одинаковые. Дизайн MSDN'а на моей памяти менялся раза три точно. Первый раз я столкнулся с ним в далёком 2001 году, но он уже тогда был красивее, чем дефолтный стиль доксигена.

    ОтветитьУдалить
  7. Да, ты прав что дефолтный стиль доксигена просто слишком тошнотворен, на фоне MSDN.

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

    И тем не менее, доксигеном можно сгенерировать документацию с приличным видом.

    ОтветитьУдалить
  8. доксигеном можно сгенерировать документацию с приличным видом.

    Скриншоты и ссылки на конфиги в студию!

    ОтветитьУдалить
  9. Здесь пример приличного видом. Конфиги не знаю, потому что, как писал ранее, никогда не пользовался доксигеном.

    ОтветитьУдалить
  10. Этот пример более-менее. Спасибо!

    ОтветитьУдалить
  11. Кстати по поводу примера. Я не уверен, но по-моему пример в последней ссылке как раз и есть дефолтный стиль доксигена или по крайней мере очень к нему близкий.

    Вообще, ты молодец, что начал эту тему. На досуге как-то может займусь созданием таблицы стилей a la MSDN для доксигена.

    ОтветитьУдалить
  12. GooRoo, это будет полезный труд. Держи нас в курсе.

    ОтветитьУдалить

Темы

2012 (2) амазон (1) анпакинг (1) артемий лебедев (4) атн (1) аудио (1) аэропорт (1) безопасность (3) бизнес (1) билайн (1) блог (2) будущее (2) видео (11) википедия (5) вымысел (16) гагарин (1) герман (1) гитхаб (1) гугл (3) дед мороз (1) декабрь (1) демотиватор (2) дети (2) дизайн (13) диссертация (2) документация (1) друзья (5) евпатория (1) евро-2012 (1) жадность (1) заяц (1) идея (1) имейл (1) инстаграм (1) интервью (5) интересное (20) интерфейс (13) история (7) как_выжить (4) календарь (1) капитализм (1) картина (1) кмб (6) книга (6) коллекция (4) компилятор (2) конкурс (5) космос (1) лаборатория (1) либералы (1) лингво (1) лузер (6) макаренко (2) макдональдс (2) математика (1) медиапорт (1) ментор (1) металлика (1) металлист (2) метро (7) микрософт (6) миргород (1) москва (2) музыка (3) наркомания (1) новости (17) образование (3) оптимизация (5) основы (14) открытки (3) ошибка (11) памятник (1) патриотизм (3) плагиат (1) плата (1) погода (3) поиск (1) политика (2) полтава (2) праздник (1) программирование (15) прошлое (2) путешествия (8) рейтинг (1) рендер (1) рисунок (2) русские (1) русский язык (1) сайт (4) санкт-петербург (1) сапр (7) сеть (1) си++ (1) синтез (1) системси (1) скриншот (40) социализм (1) соцопрос (3) спектрум (2) спорт (2) срач (2) статистика (1) такси (1) тбб (3) твитер (9) тимошенко (1) украина (5) униан (1) фан (30) фокус (1) фото (39) фотошоп (1) фурсенко (1) футбол (2) хабр (1) харьков (21) хнурэ (19) хобби (4) цитата (2) чехия (1) школа (1) эпл (1) эхостар (1) юмор (1) яндекс (1) clang (2) doxygen (1) english (3) ios (1) llvm (1) msdn (1) outlook (1) PHP (1) stackoverflow (1)

Поиск

Читатели