Стилистика статей

К оформлению статей на этом ресурсе предъявляется ряд требований и рекомендаций.

Заголовок статьи должен быть лаконичен и понятен. Если в статье описывается отдельная программа, то к её названию можно добавить краткое описание, например:

• Веб-браузер Firefox

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

Старайтесь максимально полно и подробно описывать все вопросы, затрагиваемые в статье. При этом всячески приветствуются ссылки на другие статьи, в которых более детально рассматриваются те или иные аспекты. Однако при этом не стоит отходить от темы статьи и устраивать из описания решения одного вопроса полное руководство пользователя Ubuntu Linux. Фактически, хорошая статья обязательно должна удовлетворять двум следующим требованиям:

1. Пользователь, прочитав её, должен получить полное представление об обсуждаемом вопросе, но при этом не должен искать нужную информацию среди кучи мусора, напрямую к статье не относящегося.
2. Однако при желании пользователь должен иметь возможность получить более подробную информацию по тем или иным используемым в статье аспектам. Т.е. старайтесь давать ссылки на другие статьи везде, где это возможно. Например, все стандартные операции обязаны сопровождаться ссылками на соответствующие статьи.

Любая статья, размещаемая в вики, должна составляться исходя из того, что читать её будет абсолютно неподготовленный человек. Поэтому любые потенциально опасные действия должны сопровождаться предупреждением. Например:

 sudo rm -rf directory

Если где-то в статье вы предлагаете пользователю выполнить какие-то действия, специфичные для Ubuntu и Linux в целом, то не стоит полагаться на его эрудицию. Любая нетривиальная операция должна сопровождаться ссылкой на статью по этому поводу, либо, на крайний случай, кратким описанием. Например:

Данный пример наглядно показывает преимущества ссылок вместо описания действия в текущей статье, потому как в подсказке не описаны ни побочные эффекты, возникающие при перезапуске Х-сервера (которые, согласно пункту Потенциально опасные действия данного руководства, должны быть описаны), ни неприменимость данного решения для Ubuntu 9.04.

Небольшие дополнения и пояснения, относящиеся к различным пунктам статьи, всячески приветствуются. Например:

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

Если вы просите пользователя выполнить некоторые стандартные операции, то обязательно давайте ссылку на статью, в которой описываются подобные действия. Также вы можете использовать шаблоны для описания подобных действий.

Любые команды, вводимые в консоли, надо заключать в тег <code>, либо отделять двойным пробелом, что даст тот же эффект. Например:

sudo su
rm -rf /

Однако не выделяйте таким образом команды вместе с выводом или с приглашением командной строки (кроме символов # и $, если кто ещё помнит различие между ними).

Кроме того, если необходимо включить в команду некое собирательное понятие, например, «файл», то можно, дабы не возникало путаницы, заключить его в треугольные скобки. Например:

ls -ld <директория>

Если необходимо включить название консольной утилиты в текст, то её необходимо выделить моноширинным курсивом, например:

• Утилита ls выводит содержимое текущей папки.

Не выделяйте подобным образом целые команды, т.е. названия утилит вместе с параметрами, для этого необходимо использовать тег <code>.

Листинги необходимо заключать в тег <file>, но если листинг - содержимое скрипта, то крайне желателательно использовать подсветку синтаксиса с тегом <code>. Заключать листинги в тег <code> без подсветки запрещено.

Например:

sub LoadResFile {
	local $_;
	@_ == 1 or die "Должен быть ровно 1 аргумент!\n";
	open INPUT, "<$_[0]" or die "Файл '$_[0]', Ы?\n";
	my @results;
	foreach (<INPUT>) {
		next if /^\s*$/ or /^\s*#/;			#Легко избавляемся от пустых строк и строк-комментариев
		s/#.*|[\n\r]//g;				#Легко кушаем все комментарии и переводы строк
		my @vals = /(?:\A|,)(.*?)(?=,|\Z)/g;		#Легко разделяем строчки по запятым (хм, почему не split)
		foreach $key (@vals) {
			$key =~ s!\s!!g;			#Легко удаляем все пробелы
			if ($key) { $results[@results]=$key }	#Если что-то осталось, то добавляем в результаты
		}
	}
	close INPUT;
	return @results;
}

Существует баг Firefox'а, связанный с тем, что элементы <file> и <code>, содержащие длинные строки, растягивают пространство статьи в горизонтальном направлении. Такой же эффект получается если добавить на страницу изображение большого размера. Т. к. текст масштабируется в зависимости от размеров страницы, такие статьи очень неудобно читать, особенно тем, у кого маленькие мониторы (например, пользователям нетбуков). Для того, чтобы растягивания не происходило, разбивайте такие строки на несколько строк. Например, команду

cat /home/user/folder1/folder2/folder3/folder4/folder5/folder6/folder7/folder8/folder9/folder10/folder11/folder12/folder13/folder14/folder15/some_file

можно записать:

cat /home/user/folder1/folder2/folder3/ \
folder4/folder5/folder6/folder7/folder8/ \
folder9/folder10/folder11/folder12/folder13/ \
folder14/folder15/some_file

И она, после копирования ее в терминал все равно будет работать, т. к. в конце каждой строки стоит символ \, экранирующий переход на новую строку. Аналогично можно поступать со скриптами, а в случае с листингом файлов или вывода результатов работы какой-либо программы можно просто разбивать строки. Например:

Это очень-очень-очень длинная строка, в которой написано что-то совсем не важное. Но мы то с вами знаем, что важна тут в первую очередь именно длина строки.
А это короткая строка.

Может быть записано как:

Это очень-очень-очень длинная строка, в 
    которой написано что-то совсем не важное. 
    Но мы то с вами знаем, что важна тут в 
    первую очередь именно длина строки.
А это короткая строка.

Данное требование в оформлении не обязательное, но желательное, т. к. во-первых Firefox является в Ubuntu браузером по-умолчанию, а во-вторых далеко не у каждого посетителя ресурса есть возможность смотреть его с тем же разрешением, что и у вас.

Запрещено транслитерировать английские имена. Если файловый менеджер называется Nautilus, то обзывать его Наутилусом не стоит. Фактически, нужно брать названия из меню Приложения или Система.

Кроме того, каждое слово в имени собственном приложения надо выводить с заглавной буквы, т.е. например нужно писать Synaptic и Cairo Dock, а не synaptic или Cairo dock, однако это не значит, что нужно писать Файловый Менеджер Nautilus, ибо именем собственным является только Nautilus. Кроме того, если название принято выводить в верхнем регистре, то этого правила тоже следует придерживаться, т.е. писать GNOME и KDE вместо Gnome и Kde.

Если вы пишите полное название приложения, то либо вы заключаете его в кавычки, начинаете с заглавной буквы и пишите курсивом, либо выделяете заглавными буквами только имена собственные в составе полного названия и пишите всё обычным шрифтом. Например:

1. В файлом менеджере Nautilus можно выполнять различные операции с файлами.
2. Откройте приложение «Файловый менеджер Nautilus» и зайдите в меню Правка→Параметры.

При этом курсивом надо выделять только содержимое, а не символы-кавычки.

Кроме того, не забывайте давать ссылки на статьи про упоминаемые приложения, как это сделано в предыдущем примере.

Имена любых пунктов меню необходимо писать курсивом. Кроме того, лучше не выделять их кавычками. Цепочки в любом случае в кавычки выделять нельзя. Например: Система→Параметры. А вот код, дающий такой результат:

//Система->Параметры//

Названия любых элементов необходимо выделять курсивом, и при необходимости заключать в кавычки.

При любом упоминании любой клавиши клавиатуры или любого клавиатурного сочетания необходимо использовать тег <key>:

<key>C-A-F1</key>

А выглядит это так: Ctrl+Alt+F1

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

Во первых, хочется сказать, что наш ресурс является WiKi ресурсом, и поэтому подразумевается совместная работа над статьями. Следовательно, если вы написали некую статью и поставили под ней свою подпись, вы присваиваете себе авторство и возможных дальнейших правок этой статьи, сделанных другими пользователями. Согласитесь, это не очень красиво. Конечно, в дальнейшем кто-то может просто убрать вашу подпись¹⁾, но все равно, это слабо соответствует концепции WiKi. Во-вторых, если вы все таки хотите подписаться под статьей, оставляйте, пожалуйста, ссылку на свой профиль на форуме. Это сразу предоставит желающим несколько различных способов связаться с вами (при правильно заполненном профиле), в том числе при помощи личных сообщений на форуме.