Блог им. semiletovнудная документация и тоталитаризм

Ответы на бОльшую часть вопросов, которые мне задаются пользователями о созданных мною программах, содержатся в документации. Раньше я думал, что причина нежелания читать документацию — лень. Отчасти это так и есть, но существует и еще причина — документация к ПО обычно чрезвычайно скучная. Причем скука даже возводится в какую-то священную обязанность — поглядите на предписания Debian по написанию документации. Писать скучно, выстраивать пресные слова ровными шеренгами. Одно время в состав Debian входили материалы по анархизму/анархии (не знаю, как сейчас). Однако так получается, что там, где пытаются применять анархизм на практике, получается жесткий тоталитаризм. Предписания! Всюду предписания и бюрократия!

Комментарии (11)

  • avatar
  • fog
  • 10 августа 2011, 16:16
  • #
  • 0
Мне кажется, что главная проблема документации к СПО в том, что её, зачастую, нет. :-) Не в том смысле, что нет совсем, а в том, что есть но старая, или есть, но не полная или есть, но написана так, что все-рано ничего не понятно. А скучность — это просто частный случай из этого списка.

Собственно, к проприетарному ПО документацию пишут специально обученные для этого люди. Если проект открытый и «на энтузиазме», то документацию приходится писать самим программистам. А какое главное свойство программиста? Правильно, лень. Поэтому разработчики придумывают разные системы по генерации документации, а как следствие, вся документация скучная и сухая. :-(
По-моему, документация — это что-то типа ДСП. Конечный пользователь ее все равно читать не будет. Документация — это сырье, из которого другие специально обученные люди делают что-то типа "* для чайников" :)
Я конечный пользователь многих программ и читаю документацию от начала до конца :) И напротив, книг на ИТ-тематику я не люблю — они устаревшие, они многословные. Всё, что нужно для работы с программой, должно быть заключено в документацию. Поэтому и важна такая документация, которую можно читать как хорошую книгу.
А не являешься ли ты, случайно, конечным пользователем gcc? Если да — читал ли ты его документацию от начала и до конца? Если нет, то не собираешься ли ты стать конечным пользователем gcc?
Поскольку я пользуюсь gcc, то являюсь его пользователем, и читал документацию. При этом мне не нужны сторонние источники сведений о пользовании gcc.
Специально обученные люди тоже пишут нудную документацию. Хорошую документацию может написать только энтузиаст проекта, к коему документация относится, хорошо этот проект знающий и обладающий вдобавок живым слогом. Мне нравится документация Cinelerra, Reaper, в своё время была хорошая документация к Mplayer (когда разработчики с Джо Барром ругались). К играм вроде Baldur's Gate — тоже классная.
  • avatar
  • LRN
  • 10 августа 2011, 18:13
  • #
  • 2
По-моему, понимание вопроса несколько странное.
«Скучная» — эпитет к документации не применимый. Документация может либо быть, либо не быть. Или быть неполной. Или быть устаревшей.
«Скучным» может быть туториал (т.е. учебник), который надо именно прочитать от начала до конца, чтобы научиться пользоваться программой и познать основные концепции её использования, которые позволят в дальнейшем использовать её «на ощупь» (то есть ты примерно представляешь, что и где искать, и просто исследуешь возможности по мере появления потребностей).
К документации обращаются за конкретными вопросами (когда не получается найти нужную рукоятку), читают только релевантные главы (пользуются оглавлением или полнотекстовым поиском). В документации ценятся точность и полнота. Доступность или недоступность для понимания — это скорее вопрос предметной области (хотя, корявое изложение тоже мешает). Но «живость слога» и «нескучность» тут вообще не в тему.

Кстати, это мне напомнило о недавно просмотренной презентации про gamification (была такая на Google Tech Talks; собственно, и позднее они были, но он-лайн не все можно посмотреть). Учись делать туториалы у создателей компьютерных игр.
Нашёл ссылку, вот она
Когда документация написана сухим ИТ-канцеляритом — её не хочется читать. Освоение функций сложной программы зависит напрямую от толковости документации, потому что, как правило, только документация современна текущей версии программы.
Видео кратко посмотрел — не имеет для меня пользы :)
Лучшая документация к open source программе — её код.
Звучит красиво, но практика показывает что это далеко не всегда верно.
Только зарегистрированные и авторизованные пользователи могут оставлять комментарии.