Справка:Стиль

Wiki> Содержимое руководств

Концепция — Пространства имен — Редактирование — Стиль — Порталы — Шаблоны — Категории — Значки — Шпаргалка — To Do

Это руководство рассказывает как создавать и редактировать статьи в вики что бы они соответствовали стилю принятому в openSUSE, и выглядели единообразно. Эти правила основываются на Wikipedia guidelines. Следующие руководства подробно описывают стиль оформления статей в openSUSE вики.

Содержание

1 Удобство использования
- 1.1 Нейтральный стиль
- 1.2 Краткость - сестра таланта
2 Структура
3 Содержание статьи
4 Оформление вставок
5 Смотри также
6 Внешние ссылки

Удобство использования

Нейтральный стиль

При написании текстов используйте нейтральный стиль. Не используйте местоимения "Я", "Мы" и т.п.

Краткость - сестра таланта

Говорят, что краткость — сестра таланта. Для того, чтобы излагать кратко, необходимо отделять главное от второстепенного, концентрировать изложение на контексте, убирать из текста нагромождение лишних слов.

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

Так же смотрите Article development в Википедии.

Структура

Название

Название должно быть коротким и понятным. Смотри Help:Examples of bad article title.
Не используйте редкие сокращения, если не будете уверены что они широко известны.
Не используйте составные слова CamelCase. Вместо этого используйте пробелы.
Используйте заглавные буквы так же как это принято в Wikipedia.
Не используйте двоеточие как разделитель в заголовке. Смотри Двоеточие в заголовке.
Не используйте специальные символы. Используйте только [aA-zZ][аА-яЯ][0-9].

Названия разделов

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

Создание разделов

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

Запрещено: Одиночный знак равенства (=) создает название раздела такого же размера как и название статьи, что не принято в обычном стиле написания статей.

Не вставляйте ссылок в заголовки. Вместо этого лучше вставить ссылку в раздел сразу же после заголовка.
Разделяйте очень длинный разделы на несколько подразделов.
Используйте ---- чтобы создать горизонтальную линию перед каждым заголовком раздела 2-го уровня (==), это сделает статью более наглядной.

Пример:

 ==раздел 1==
 ===подраздел 1.1===
 ===подраздел 1.2===
 
 ----
 ==раздел 2==
 ===подраздел 2.2===
 ====подраздел 2.2.1====
 =====подраздел 2.2.1.1=====

 ----
 ==раздел 3==

Содержание статьи

Как правильно писать openSUSE

openSUSE единственно верное написание бренда openSUSE. "OpenSUSE", "openSuSE", OpenSuse" и другие возможные варианты оформления не верны. Так как MediaWiki не позволяет создавать заголовки статей начинающиеся с маленькой буквы, если захотите создать статью начинающуюся с "openSUSE" используйте шаблон Шаблон:Lowercase_title.
Не используйте символы торговой марки (такие как © или ®) так как это мешает чтению статьи.
Написание "SuSE Linux" или "SUSE Linux" резко осуждается. За исключением случаев когда надо недвусмысленно сослаться на старый релиз openSUSE (10.1 и более ранние) для исторической справки, или на SUSE Linux Enterprise Server (SLES) и SUSE Linux Enterprise Desktop (SLED), в остальных случаях используйте "openSUSE".

Дублирование материалов

Не делайте лишнюю работу.

Проверьте список HOWTOs openSUSE. Там собрана большая коллекция статей. Возможно уже существует статья о предмете который вы хотели описать, потратьте время и прочтите ее, возможно более целесообразно будет улучшить уже имеющуюся статью, чем писать новую.
Форум openSUSE так же содержит большую коллекцию HOWTOs в разделе Advanced How To/FAQ (read only), основной форум и в частности под форум Unreviewed How To and FAQ уже могут содержать материалы по вашей теме, на который вы можете опереться в создании статьи.
А так же имеется огромная коллекция HOWTO статей на The Linux Documentation Project.

Сокращения и аббревиатуры

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

Переменные

Иногда указанные в статье команды должны содержать данные зависящие от конкретной системы, например имена пользователей или названия устройств. В эти места команды пользователь должен самостоятельно подставить свои данные. При указании таких команд применяйте следующие соглашения:

<имя пользователя>, пример использования /home/<имя пользователя>
sdX для устройств

Обратите внимание:

В связи с вышеуказанными требованиями следует заменять обычно используемые указания устройств и имен пользователя такие как (sda, sdb, hda, и т.д.) на sdX.
Если разговор идет о нескольких устройствах используйте следующие обозначения sdX, sdY, sdZ. Если появится необходимость указать более трех различных устройств, необходимо использовать sdN где N начинается с последних букв английского алфавита.

Заботьтесь о новичках

Заботьтесь о новичках и пытайтесь не допустить возможности повредить систему новичка, из за того что он может не понимать действия команд.

Внимание: Особенно это относится к указанию команд требующих прав суперпользователя. Такие команды как dd, rm, fdisk, могут серьезно повредить систему пользователя при их бездумном использовании. Новички достаточно часто применяют эти команды без понимания их работы, просто копируя и вставляя их в командную строку.

Не используйте в примерах такие команды которые можно просто скопировать и вставить в командную строку и при этом их выполнение сможет нанести вред системе. Вот пример такой команды:

# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sda

если ее выполнить то произойдет перезапись первого диска в системе пользователя. Потому что /dev/sda первый диск который присутствует на большинстве компьютеров. В то время как тупо скопированная команда:

# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sdX

не сможет нанести значительного вреда, так как маловероятно что в системе существует устройство /dev/sdX, и выполнение такой команды скорей всего вызовет ошибку(это лучше чем перезапись sda).

Изображения

Размещение

Смотрите инструкции к Wikipedia как лучше подготовить изображение к загрузке. А так же инструкции как правильно размещать изображения.

Форматы

Схемы, иконки, снимки экрана и другие изображения(обычно имеющие достаточно большой размер и содержащие блоки одного цвета) лучше всего размещать в формате PNG.
Фотографии в формате JPEG.
Анимацию в формате GIF.

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

Цвета

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

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

 <!-- Этот комментарий будет не виден читателю.  -->

Требуемые страницы

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

Оформление вставок

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

Wiki разметка

Везде где необходимо использовать HTML теги для форматирования страницы, используйте вместо этого разметку MediaWiki , это сделает чтение и редактирование статьи более простым. Для получение информации о wiki разметке вы можете использовать Wiki Reference card и исходный код других статей.

Комбинации кнопок

F5 и Tab

Код: <code>Кнопка которую надо нажать</code>
Описание: Клавиша на клавиатуре.
Где используется: В любом месте статьи

Пути

/usr/src/linux и /etc/SuSE-release

Код: <tt>/path/to/directory/or/file</tt>
Описание: Указание пути к каталогу или файлу.
Где используется: В любом месте статьи

Команда для ввода

$ user command

# root command

Код: {{Shell|$ user command}} или <div class="shell"># root command</div>
Описание: Пример команды для ввода в командую строку.
Где используется: В любом месте статьи

Вывод команды

output text

Код: (пробел)короткий текст вывода или <pre>длинный вывод команды</pre>
Описание: Указывается результат действия команды и ее вывод.
Где используется: В любом месте статьи

Протоколы собраний

... Содержание ...

Код: <div class="minutes"> ... Content ... </div>
Описание: Для оформления протоколов собраний.
Где используется: В любом месте статьи

Таблицы

Заголовок 1	Заголовок 2	Заголовок 3	Заголовок 4	Заголовок 5	Заголовок 6
Выделенный текст	Выделенный текст	Выделенный текст	Text	Text	Выделенный текст
Text	Text	Text	Text	Text	Выделенный текст
Text	Text	Text	Text	Text	Выделенный текст

Код: Смотри исходники на странице правки.
Описание: Таблица с выделением ячеек.
Где используется: В любом месте статьи

Шаблоны

Смотри Wiki Template Guidelines.

Смотри также

Внешние ссылки

Справка:редактирование для Wikipedia