Содержание
К оформлению статей на этом ресурсе предъявляется ряд требований и рекомендаций.
Заголовок статьи
Заголовок статьи должен быть лаконичен и понятен. Если в статье описывается отдельная программа, то к её названию можно добавить краткое описание, например:
- Веб-браузер Firefox
Не стоит писать в заголовок версию программы или операционной системы. Исключениями являются статьи, описывающие версии программ, которые кардинально отличаются друг от друга.
Содержание статей
Старайтесь максимально полно и подробно описывать все вопросы, затрагиваемые в статье. При этом всячески приветствуются ссылки на другие статьи, в которых более детально рассматриваются те или иные аспекты. Однако при этом не стоит отходить от темы статьи и устраивать из описания решения одного вопроса полное руководство пользователя Ubuntu Linux. Фактически, хорошая статья обязательно должна удовлетворять двум следующим требованиям:
- Пользователь, прочитав её, должен получить полное представление об обсуждаемом вопросе, но при этом не должен искать нужную информацию среди кучи мусора, напрямую к статье не относящегося.
- Однако при желании пользователь должен иметь возможность получить более подробную информацию по тем или иным используемым в статье аспектам. Т.е. старайтесь давать ссылки на другие статьи везде, где это возможно. Например, все стандартные операции обязаны сопровождаться ссылками на соответствующие статьи.
Потенциально опасные действия
Любая статья, размещаемая в вики, должна составляться исходя из того, что читать её будет абсолютно неподготовленный человек. Поэтому любые потенциально опасные действия должны сопровождаться предупреждением. Например:
sudo rm -rf directory
Данная команда должна быть выполнена в точности так, как приведено в этом руководстве. Будучи выполнена иначе, в другом каталоге или с ошибками в наборе, эта команда может удалить любые данные с вашего компьютера!
Нетривиальные действия
Если где-то в статье вы предлагаете пользователю выполнить какие-то действия, специфичные для Ubuntu и Linux в целом, то не стоит полагаться на его эрудицию. Любая нетривиальная операция должна сопровождаться ссылкой на статью по этому поводу, либо, на крайний случай, кратким описанием. Например:
… необходимо перезапустить X-сервер …
Данный пример наглядно показывает преимущества ссылок вместо описания действия в текущей статье, потому как в подсказке не описаны ни побочные эффекты, возникающие при перезапуске Х-сервера (которые, согласно пункту Потенциально опасные действия данного руководства, должны быть описаны), ни неприменимость данного решения для 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; }
<code>
и <file>
ни для каких других целей, кроме вышеобозначенных.
Существует баг 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.
Если вы пишите полное название приложения, то либо вы заключаете его в кавычки, начинаете с заглавной буквы и пишите курсивом, либо выделяете заглавными буквами только имена собственные в составе полного названия и пишите всё обычным шрифтом. Например:
- В файлом менеджере Nautilus можно выполнять различные операции с файлами.
- Откройте приложение «Файловый менеджер Nautilus» и зайдите в меню Правка→Параметры.
При этом курсивом надо выделять только содержимое, а не символы-кавычки.
Кроме того, не забывайте давать ссылки на статьи про упоминаемые приложения, как это сделано в предыдущем примере.
Имена пунктов меню в системе и приложениях
Имена любых пунктов меню необходимо писать курсивом. Кроме того, лучше не выделять их кавычками. Цепочки в любом случае в кавычки выделять нельзя. Например: Система→Параметры. А вот код, дающий такой результат:
//Система->Параметры//
Названия различных элементов на диалоговых окнах
Названия любых элементов необходимо выделять курсивом, и при необходимости заключать в кавычки.
Клавиатурные сочетания
При любом упоминании любой клавиши клавиатуры или любого клавиатурного сочетания необходимо использовать тег <key>:
<key>C-A-F1</key>
А выглядит это так: Ctrl+Alt+F1
Ссылки на другие ресурсы
Если вы используете в статье технические термины и узкоспециальные понятия, то хорошо бы давать ссылки на энциклопедические ресурсы, в которых они описываются. В качестве основного подобного ресурса можно использовать Википедию. Однако категорически запрещено вставлять ссылки на непроверенные ресурсы, ресурсы, изобилующие рекламой, так же нежелательны ссылки на сайты с документацией других дистрибутивов Linux.
Подписи и авторство статей
Во первых, хочется сказать, что наш ресурс является WiKi ресурсом, и поэтому подразумевается совместная работа над статьями. Следовательно, если вы написали некую статью и поставили под ней свою подпись, вы присваиваете себе авторство и возможных дальнейших правок этой статьи, сделанных другими пользователями. Согласитесь, это не очень красиво. Конечно, в дальнейшем кто-то может просто убрать вашу подпись1), но все равно, это слабо соответствует концепции WiKi. Во-вторых, если вы все таки хотите подписаться под статьей, оставляйте, пожалуйста, ссылку на свой профиль на форуме. Это сразу предоставит желающим несколько различных способов связаться с вами (при правильно заполненном профиле), в том числе при помощи личных сообщений на форуме.