Записки программиста

На официальных сайтах многих проектов можно обнаружить мануалы в формате PDF. В частности, такие мануалы есть у Akka, Cassandra, MongoDB и PostgreSQL. У MariaDB такую документацию, к сожалению, найти не удалось, да и сам раздел с документацией был обнаружен исключительно благодаря Google. Также, к сожалению, не удалось найти официальной документации в формате PDF по Riak и RabbitMQ.

Лично я нахожу такую документацию крайне полезной за счет ее (1) актуальности (2) полноты и (3) возможности быть прочтенной оффлайн. Думается, что наличие такой документации является признаком серьезности и зрелости проекта. Наводит на интересные мысли явная корреляция основного языка программирования проекта и наличия или отсутствия документации. Ну да поведать я хотел не об этом.

К сожалению, иногда документация оказывается чрезмерно подробной. Например, мануал по MongoDB занимает 800 страниц. А документация по PostgreSQL — так и вовсе более 2000 страниц! Да, мне хотелось бы детальной документации с описанием всяких там граничных случаев и так далее. Но 800 и более страниц, как по мне, это перебор. В конце концов, если уж я взялся за чтение полной документации по MongoDB, можно предположить, что, наверное, я знаю, что такое индексы. Вот, например, 300-400 страниц, как в случае с Akka — в самый раз. Да и там количество примеров можно было бы существенно сократить.

В общем, было бы здорово помимо всеобъемлющей документации иметь еще и какую-то сокращенную версию. Однако что-то мне подсказывает, что никто не станет такими вещами заморачиваться и придется по старинке пробегать неинтересные места глазами. Думается, что для краткого описания наиболее важных или не совсем очевидных вещей и нужны блоги.

А что вы думаете касательно полезности такой документации и часто ли вы ее читаете?

Метки: Философия.