Блог им. semiletov → нудная документация и тоталитаризм
Ответы на бОльшую часть вопросов, которые мне задаются пользователями о созданных мною программах, содержатся в документации. Раньше я думал, что причина нежелания читать документацию — лень. Отчасти это так и есть, но существует и еще причина — документация к ПО обычно чрезвычайно скучная. Причем скука даже возводится в какую-то священную обязанность — поглядите на предписания Debian по написанию документации. Писать скучно, выстраивать пресные слова ровными шеренгами. Одно время в состав Debian входили материалы по анархизму/анархии (не знаю, как сейчас). Однако так получается, что там, где пытаются применять анархизм на практике, получается жесткий тоталитаризм. Предписания! Всюду предписания и бюрократия!
- -1
- semiletov
- 10 августа 2011, 15:14
Собственно, к проприетарному ПО документацию пишут специально обученные для этого люди. Если проект открытый и «на энтузиазме», то документацию приходится писать самим программистам. А какое главное свойство программиста? Правильно, лень. Поэтому разработчики придумывают разные системы по генерации документации, а как следствие, вся документация скучная и сухая. :-(
«Скучная» — эпитет к документации не применимый. Документация может либо быть, либо не быть. Или быть неполной. Или быть устаревшей.
«Скучным» может быть туториал (т.е. учебник), который надо именно прочитать от начала до конца, чтобы научиться пользоваться программой и познать основные концепции её использования, которые позволят в дальнейшем использовать её «на ощупь» (то есть ты примерно представляешь, что и где искать, и просто исследуешь возможности по мере появления потребностей).
К документации обращаются за конкретными вопросами (когда не получается найти нужную рукоятку), читают только релевантные главы (пользуются оглавлением или полнотекстовым поиском). В документации ценятся точность и полнота. Доступность или недоступность для понимания — это скорее вопрос предметной области (хотя, корявое изложение тоже мешает). Но «живость слога» и «нескучность» тут вообще не в тему.
Кстати, это мне напомнило о недавно просмотренной презентации про gamification (была такая на Google Tech Talks; собственно, и позднее они были, но он-лайн не все можно посмотреть). Учись делать туториалы у создателей компьютерных игр.
Видео кратко посмотрел — не имеет для меня пользы :)