RTFM

Оказывается, использование кавычек Иван придумал не сам: спросил у товарища, опытного пользователя Linux по фамилии Гончаров. Гончаров охотно показал, где ставить кавычки, а вот объяснять, что они делают, отказался: ”Там отличное руководство! Читай!”.

Документация в Linux играет важнейшую роль. Решение любой задачи должно начинаться с изучения руководств. Не стоит жалеть на это времени. Даже если рядом есть опытный пользователь Linux, который, возможно, знает ответ, не стоит беспокоить его сразу же. Возможно, даже зная, что нужно сделать, он не помнит как именно - и поэтому (а также потому, что он - опытный пользователь) начнет с изучения руководства. Это - закон, у которого даже собственное название: RTFM, что означает ”Read The Fine Manual”.

RTFM, Read The Fine Manual — правило, согласно которому решение любой задачи надо начинать с изучения документации.

Слова Гончарова - практически дословный перевод этой фразы, так что ее смысл и происхождение очевидны. Linux рассчитан в основном на тех, кто хочет знать, как им пользоваться.

Руководство — это не учебник, а скорее справочник. В нем содержится информация, достаточная для освоения описываемого объекта, но никаких обучающих приемов, никаких определений, повторений и выделения главного в нем обычно нет.

Тем более не допускается усечение руководства с целью представить небольшие по объему, но наиболее важные сведения. Так принято в учебниках, причем сведения раскрываются и объясняются очень подробно, а остальные присутствуют в виде ссылки на документацию для профессионалов. Страницы руководств - и есть эта самая документация для профессионалов.

Руководство чаще всего читает человек, который уже знает, о чем оно.

Это не значит, что из руководства нельзя понять, как, например, пользоваться командой в простейших случаях. Напротив, часто встречается поле EXAMPLES, которое как раз и содержит примеры использования команды в разных условиях. Однако все это призвано не научить, а раскрыть смысл, пояснить сказанное в других полях. Иван нашел описание работы двойных кавычек в руководстве по sh, однако понял из него далеко не все - главным образом, потому, что встретил слишком много незнакомых терминов.

Система info может содержать больше, чем man, поэтому в нее часто включают и учебники (принято называть учебник термином ”tutorial”), и ”howto” (примеры постановки и решения типовых задач), и даже статьи по теме. Таким образом, info-документ может стать, в отличие от страницы руководства, полным сводом сведений. Разработка такого документа - дело трудоемкое, поэтому далеко не все объекты системы им сопровождаются. Кроме того, и прочесть большой info-документ целиком зачастую невозможно. Поэтому имеет смысл начинать именно с руководства, а если его недостаточно - изучать info.

Если некоторый объект системы не имеет документации ни в формате man, ни в формате info, это нехорошо. В этом случае можно надеяться, что при нем есть сопроводительная документация, не имеющая, увы, ни стандартного формата, ни тем более ссылок на руководства по другим объектам системы. Такая документация (равно как и примеры использования объекта) обычно помещается в каталог /usr/share/doc/имя-объекта.

Документация в подавляющем большинстве случаев пишется на простом английском языке. Если английский — не родной язык для автора документации, она будет только проще. Традиция писать по-английски идет от немалого вклада США в развитие компьютерной науки вообще и Linux в частности. Кроме того, английский становится языком международного общения во всех областях, не только в компьютерной. Необходимость писать на языке, который будет более или менее понятен большинству пользователей, объясняется постоянным развитием Linux. Дело не в том, что страницу руководства нельзя перевести, а в том, что ее придется переводить всякий раз, когда изменится описываемый ею объект! Например, выход новой версии программного продукта сопровождается изменением его возможностей и особенностей работы, а следовательно, и новой версией документации. Тогда перевод этой документации превращается в ”moving target”, сизифов труд.