Различия

Здесь показаны различия между двумя версиями данной страницы.

--- справка:стилистика_статей [2013/03/22 15:11]
скопировал с стилистика_статей
+++ справка:стилистика_статей [2013/03/22 15:56] (текущий)
@@ Строка 1: / Строка 1: @@
-====== Руководство по стилистике статей ======
+====== Стилистика статей ======
-<note> Не забудьте так же ознакомиться с [[содержание статей|требованиями по содержанию статей]]. </note>
-<note important> Из-за глюка вики при преобразовании кавычек в "ёлочки" подобная конструкция отображается неверно: %%"//test//"%%, поэтому если необходимо, вставляйте кавычки-"ёлочки" явно (копирование-вставка - хорошая вещь)</note>
-<note>Вы всегда можете просмотреть исходный код статьи чтоб понять что к чему</note>
-<note important> Внимание! Чтобы статья не потерялась, настоятельно рекомендуется использовать тэги.\\ О том, как это делать, смотрите ниже.</note>
-===== Оформление команд =====
+К оформлению статей на этом ресурсе предъявляется ряд требований и рекомендаций.
+===== Заголовок статьи =====
+Заголовок статьи должен быть лаконичен и понятен. Если в статье описывается отдельная программа, то к её названию можно добавить краткое описание, например:
+  * Веб-браузер Firefox
+Не стоит писать в заголовок версию программы или операционной системы. Исключениями являются статьи, описывающие версии программ, которые кардинально отличаются друг от друга.
+===== Содержание статей =====
+Старайтесь максимально полно и подробно описывать все вопросы, затрагиваемые в статье. При этом всячески приветствуются ссылки на другие статьи, в которых более детально рассматриваются те или иные аспекты. Однако при этом не стоит отходить от темы статьи и устраивать из описания решения одного вопроса полное руководство пользователя Ubuntu Linux. Фактически, хорошая статья обязательно должна удовлетворять двум следующим требованиям:
+  - Пользователь, прочитав её, должен получить полное представление об обсуждаемом вопросе, но при этом не должен искать нужную информацию среди кучи мусора, напрямую к статье не относящегося.
+  - Однако при желании пользователь должен иметь возможность получить более подробную информацию по тем или иным используемым в статье аспектам. Т.е. старайтесь давать ссылки на другие статьи везде, где это возможно. Например, все стандартные операции обязаны сопровождаться ссылками на соответствующие статьи.
+==== Потенциально опасные действия ====
+Любая статья, размещаемая в вики, должна составляться исходя из того, что читать её будет абсолютно неподготовленный человек. Поэтому любые потенциально опасные действия должны сопровождаться предупреждением. Например:
+<note warning> Будьте осторожны при выполнении команды
+   sudo rm -rf directory
+Данная команда должна быть выполнена в точности так, как приведено в этом руководстве. Будучи выполнена иначе, в другом каталоге или с ошибками в наборе, эта команда может удалить **любые** данные с вашего компьютера!</note>
+==== Нетривиальные действия ====
+Если где-то в статье вы предлагаете пользователю выполнить какие-то действия, специфичные для Ubuntu и Linux в целом, то не стоит полагаться на его эрудицию. Любая нетривиальная операция должна сопровождаться ссылкой на статью по этому поводу, либо, на крайний случай, кратким описанием. Например:
+<quote>... необходимо [[tips:x|перезапустить X-сервер]] ...
+<note tip> Для перезапуска Х-сервера нажмите <key>C-A-Backspace</key> </note>
+</quote>
+Данный пример наглядно показывает преимущества ссылок вместо описания действия в текущей статье, потому как в подсказке не описаны ни побочные эффекты, возникающие при перезапуске Х-сервера (которые, согласно пункту [[#Потенциально_опасные_действия|Потенциально опасные действия]] данного руководства, должны быть описаны), ни неприменимость данного решения для Ubuntu 9.04.
+==== Дополнения, примечания, советы и подсказки ====
+Небольшие дополнения и пояснения, относящиеся к различным пунктам статьи, всячески приветствуются. Например:
+<note tip> Вы так же можете воспользоваться <//подставить нужный инструмент//> </note>
+Однако не забывайте, что статья должна быть как можно более лёгкой к усвоению, поэтому не замусоривайте её ненужной информацией. В любом случае лучше дать ссылку на статью, в которой обсуждается та или иная проблема, чем вставлять пусть даже краткое обсуждение напрямую в свою статью.
+==== Стандартные операции ====
+Если вы просите пользователя выполнить некоторые стандартные операции, то **обязательно** давайте ссылку на статью, в которой описываются подобные действия. Также вы можете использовать [[шаблоны#стандартные_операции|шаблоны]] для описания подобных действий.
+===== Оформление статей =====
+==== Команды ====
 Любые команды, вводимые в консоли, надо заключать в тег ''%%<code>%%'', либо отделять двойным пробелом, что даст тот же эффект. Например:
@@ Строка 19: / Строка 59: @@
 Не выделяйте подобным образом целые команды, т.е. названия утилит вместе с параметрами, для этого необходимо использовать тег ''%%<code>%%''.
-===== Листинги (содержимое текстовых файлов и вывод команд) =====
+==== Листинги (содержимое текстовых файлов и вывод команд) ====
 Листинги необходимо заключать в тег ''%%<file>%%'', но если листинг - содержимое скрипта, то крайне желателательно использовать [[wiki:syntax#подсветка_синтаксиса|подсветку синтаксиса]] с тегом ''%%<code>%%''. Заключать листинги в тег ''%%<code>%%'' без подсветки запрещено.
@@ Строка 44: / Строка 84: @@
 </code>
-<note warning> Не используйте теги ''<code>'' и ''<file>'' ни для каких других целей, кроме вышеобозначенных </note>
+<note warning> Не используйте теги ''<code>'' и ''<file>'' ни для каких других целей, кроме вышеобозначенных.</note>
 Существует баг [[wiki:firefox|Firefox'а]], связанный с тем, что элементы %%<file>%% и %%<code>%%, содержащие  длинные строки, растягивают пространство статьи в горизонтальном направлении. Такой же эффект получается если добавить на страницу изображение большого размера. Т. к. текст масштабируется в зависимости от размеров страницы, такие статьи очень неудобно читать, особенно тем, у кого маленькие мониторы (например, пользователям нетбуков). Для того, чтобы растягивания не происходило, разбивайте такие строки на несколько строк.  Например, команду
@@ Строка 72: / Строка 112: @@
 Данное требование в оформлении не обязательное, но желательное, т. к. во-первых [[wiki:firefox|Firefox]] является в [[wiki:ubuntu|Ubuntu]] браузером по-умолчанию, а во-вторых далеко не у каждого посетителя ресурса есть возможность смотреть его с тем же разрешением, что и у вас.
-===== Названия приложений =====
+==== Названия приложений ====
 **Запрещено** транслитерировать английские имена. Если файловый менеджер называется Nautilus, то обзывать его Наутилусом не стоит. Фактически, нужно брать названия из меню //Приложения// или //Система//.
-Кроме того, каждое слово в имени собственном приложения надо выводить с заглавной буквы, т.е. например нужно писать Synaptic и Cairo Dock, а не synaptic или Cairo dock, однако это не значит, что нужно писать Файловый Менеджер Nautilus, ибо именем собственым является только Nautilus. Кроме того, если название принято выводить в верхнем регистре, то этого правила тоже следует придерживаться, т.е. писать GNOME и KDE вместо Gnome и Kde.
+Кроме того, каждое слово в имени собственном приложения надо выводить с заглавной буквы, т.е. например нужно писать Synaptic и Cairo Dock, а не synaptic или Cairo dock, однако это не значит, что нужно писать Файловый Менеджер Nautilus, ибо именем собственным является только Nautilus. Кроме того, если название принято выводить в верхнем регистре, то этого правила тоже следует придерживаться, т.е. писать GNOME и KDE вместо Gnome и Kde.
 Если вы пишите полное название приложения, то либо вы заключаете его в кавычки, начинаете с заглавной буквы и пишите //курсивом//, либо выделяете заглавными буквами только имена собственные в составе полного названия и пишите всё обычным шрифтом. Например:
@@ Строка 86: / Строка 126: @@
 Кроме того, не забывайте давать ссылки на статьи про упоминаемые приложения, как это сделано в предыдущем примере.
-===== Имена пунктов меню в системе и приложениях =====
+==== Имена пунктов меню в системе и приложениях ====
 Имена любых пунктов меню необходимо писать //курсивом//. Кроме того, лучше не выделять их кавычками. Цепочки в любом случае в кавычки выделять нельзя. Например: //Система->Параметры//. А вот код, дающий такой результат:
 <code>//Система->Параметры//</code>
-===== Названия различных элементов на диалоговых окнах =====
+==== Названия различных элементов на диалоговых окнах ====
 Названия любых элементов необходимо выделять //курсивом//, и при необходимости заключать в кавычки.
-===== Клавиатурные сочетания ======
+==== Клавиатурные сочетания =====
 При любом упоминании любой клавиши клавиатуры или любого клавиатурного сочетания необходимо использовать тег %%<key>%%:
@@ Строка 101: / Строка 141: @@
 А выглядит это так: <key>C-A-F1</key>
+===== Ссылки на другие ресурсы =====
+Если вы используете в статье технические термины и узкоспециальные понятия, то хорошо бы давать ссылки на **энциклопедические** ресурсы, в которых они описываются. В качестве основного подобного ресурса можно использовать Википедию. Однако категорически запрещено вставлять ссылки на непроверенные ресурсы, ресурсы, изобилующие рекламой, так же нежелательны ссылки на сайты с документацией других дистрибутивов Linux.
-====== Общая сводка стилей ======
+===== Подписи и авторство статей =====
-//Курсив//
+Во первых, хочется сказать, что наш ресурс является WiKi ресурсом, и поэтому подразумевается совместная работа над статьями. Следовательно, если вы написали некую статью и поставили под ней свою подпись, вы присваиваете себе авторство и возможных дальнейших правок этой статьи, сделанных другими пользователями. Согласитесь, это не очень красиво. Конечно, в дальнейшем кто-то может просто убрать вашу подпись((и поставить свою =) )), но все равно, это слабо соответствует концепции WiKi.
+Во-вторых, если вы все таки хотите подписаться под статьей, оставляйте, пожалуйста, ссылку на свой профиль на форуме. Это сразу предоставит желающим несколько различных способов связаться с вами (при правильно заполненном профиле), в том числе при помощи личных сообщений на форуме.
-  * Используется для названий пунктов меню и элементов диалоговых окон, а так же для названий приложений, заключённых в кавычки.
-\\
-''моноширинный шрифт''
-  * Используется для названий пакетов в тексте (напр, ''lm-sensors'')
-\\
-''//моноширинный курсив//''
-  * Используется для названий консольных утилит в тексте, для выделения команд используйте %%<code>%%!
-\\
-**Полужирный шрифт**
-  * Используется для логического выделения важных моментов в тексте, **не используйте** полужирный шрифт для выделения названий приложений, пакетов, пунктов меню и проч.
-\\
-<key>C-A-del</key>
-  * Используется для обозначения клавиатурных клавиш и сочетаний
-\\
-  Так выделяются консольные команды, которые должен ввести пользователь
-<file>Так выделяется содержимое текстовых файлов (не скриптов), а так же текстовый вывод команд (например, вывод команды ls)</file>
-<code perl>
-#!/usr/bin/perl
-# Так выделяется содержимое скриптов и программный код
-print OUTFILE "Содержимое скриптов",$_[1];</code>
-\\
-<note tip> Так выделяются подсказки, советы, рекомендации или общие примечания. </note>
+{{tag>Справка Служебная_статья инструкция FIXME}}
-<note important> Так выделяются важные вещи, на которые стоит обратить внимание. </note>
-<note warning> Так выделяются предупреждения о потенциально опасных действиях. Например, хорошо бы сопровождать команду //''rm''// подобным предупреждением. </note>

Стилистика статей Сравнение версий

Различия