РУКОВОДСТВО ПО РЕДАКТИРОВАНИЮ ВИКИ
Эта статья предназначена для людей, желающих редактировать вики Debian.
Есть также Быстрый старт для новичков.
Если Вам нужна помощь для работы с moinmoin, посетите соответствующую страницу - HelpContents. Есть в наличии и справка о синтаксисе '''moinmoin'''. Вы можете экспериментировать в вики-песочнице.
Если Вы нашли ошибку или несогласны с чем-либо, что изложено ниже, закомментируйте соответствующую строку, затем создайте новое обсуждение в соответствующем разделе.
Ваш аккаунт
Ваше вики-имя должно быть в формате "FirstnameLastname" ("IrcNickname" или Ваш логин разработчика Debian тоже подойдут).
Поправьте настройки часового пояса в настройках Вашего аккаунта - userprefs.
Ваша личная вики-страница
При создании Вашей личной вики-страницы Вы можете использовать шаблон личной страницы HomepageTemplate. На личной странице можно оставить следующую информацию.
- Ваше полное имя.
- Ваша домашняя страничка вне этой вики.
- Ваш e-mail.
Ваше местонахождение (город и страна) может быть полезно для совместной работы с людьми из разных часовых поясов.
- Если Вы пользуетесь IRC, Ваш сервер, канал и ник.
Если Вы являетесь разработчиком Debian (DD), Ваш логин (с ссылкой на http://qa.debian.org/developer.php?login=foobar@debian.org).
Неразработчики могут ссылаться на http://bugs.debian.org/from:foo@bar.com.
- Тематика Ваших интересов (не обязательно должна иметь отношение к Debian).
Ваш ToDo-лист.
- Полностью или частично Ваш вклад в развитие открытого ПО (отчеты об ошибках; написание статей или перевод их; разработка/поддержка...)
Удостоверьтесь, что проставили тег CategoryHomepage в конце Вашей личной страницы (есть по умолчанию в шаблоне HomepageTemplate).
Подписка
- Вы можете подписаться на странички, интересующие Вас.
Забыли пароль?
Если Вы потеряли или забыли пароль от своего вики-акканута, пройдите на страничку восстановления пароля(recoverpass), затем следуйте инструкциям (напишите Ваш email и нажмите кнопку "Отправить мне данные моей учетной записи").
Стили написания / Вики-этикет
Есть по меньшей мере 5 основных стилей вики-страниц
Для более подробной информации воспользуйтесь указанными ссылками.
Попробуйте соблюдать баланс, когда пишете. Избегайте перекосов. Если Вы знаете, что Ваши комментарии носят спорный характер, подчеркните это, чтобы остальные чувствовали себя более свободными, чтобы опровергнуть их или привести альтернативную точку зрения.
- Не создавайте бесполезных вики-страниц с бесполезными именами. Знайте, создание новой вики-страницы - одна из самых трудных сторон вики-работы.
В вики-вселенной нет идеальных статей. Каждая может быть усовершенствована! Смотрите RefactoringWikiPages для более полной информации.
If the wiki topic is fairly long, then it would be good style to give a quick overview of what has been discussed in the topic as a sort of concluding paragraph. If a concluding paragraph cannot be easily written then perhaps the scoping of the topic was not right, and it should either be separated into subtopics or merged with others into one larger topic. This is common when ThreadMode meanders off topic.
Смотрите также GoodStyle.
Ссылки
Не злоупотребляйте ссылками. Если их слишком много, читатель не будет знать, какая из них наиболее полезна. Вы можете вставить несколько ссылок в раздел "See also", располагающийся внизу страницы (но опять же, не слишком много).
Когда ссылки ведут к страницам на другом языке, добавляйте "(in $language)", вот так: ?Something (in French)
Смотрите также помощь по moinmoin
Внутренние ссылки
Внутренние ссылки (в границах этой вики)
[[FooPage]] - предпочитаемый синтаксис. Например, [[ru/DebianWiki/Contact]] - ru/DebianWiki/Contact.
[[SomeParentPagewith/FooPage|FooPage]] - часто используется, чтобы сократить длинную ссылку. Например, [[ru/DebianWiki/Contact|Contact]] - Contact.
[[EditorGuide|editor guide]] может быть использовано для того, что привести ссылку в нормальном виде, то есть полностью написанной строчными буквами. Например, [[ru/DebianWiki/Contact|связь с людьми, работающими над вики Debian]] - связь с людьми, работающими над вики Debian.
Не "переименовывайте" коренным образом ссылки, используя [[PageName|Another title]] (если Вы делаете так, то, возможно, это говорит о том, что статья по ссылке неправильно названа).
В любом случае, Вы должны быть уверены, что ссылка понятна для читателей, и что она не ведет куда-то, куда не следует (в лучшем случае, ссылка должна иметь такое же имя, как и у страницы, куда она ведет).
Для ссылки на подраздел внутри статьи, Вы должны определить место, используя т.н. якорь (anchor) - <<Anchor(bar)>> (смотрите HelpOnMacros), тогда используйте [[#bar|Bar Chapter]] или [[Foo#bar|Bar Chapter]] (где Bar Chapter - это название параграфа). Например, в начале раздела "Ссылки" настоящей статьи поставлен якорь links (<<Anchor(links)>>, можно посмотреть в "Правка" в самом верху страницы, только не изменяйте ничего, если новичок). Теперь можно ссылаться на параграф "Ссылки" настоящей статьи используя конструкцию [[#links|Ссылки]] - Ссылки. Или же ссылка на параграф другой страницы [[DebianWiki/EditorGuide#links|Links]] - Links.
Ссылки на внешние сайты
Предпочтительный способ ссылаться на внешние ресурсы:
http://www.debian.org/doc/ - официальная документация Debian (код выглядит так - [[http://www.debian.org/doc/]]).
(избегайте записей, скрывающих само тело ссылки [[http://www.foo.com|link label]], кроме тех случаев, когда этого требует контекст, например "Вася Пупкин предоставил скрипт test.sh.")
- Группу внешних ссылок располагайте в конце статьи, в соответствующем разделе.
Назовите этот раздел External links или Внешние ссылки.
Все странички проектов могут быть размещены в указанном разделе или, если нет других внешних ссылок, в раздел See also (или по другому Смотрите также).
Используйте InterWiki-формат, чтобы ссылаться на пакеты Debian, отчеты об ошибках, стандарты и статьи википедии.
Ссылки с внешних сайтов
Если на страницу вики ссылаются из других ресурсов Debian, полезным будет пометить эту страницу тегом CategoryPermalink, чтобы никто не смог по ошибке её удалить.
Форматирование
Header section
Материал, который располагается вверху страницы в header-области, включает в себя:
- Ссылки на альтернативные языковые версии (убедитесь, что они правильны!):
Translation(s): [[de/DebianWiki/EditorGuide|Deutsch]] - [[fr/DebianWiki/EditorGuide|Français]]
Ссылка на страницу Discussion, для обсуждения спорных моментов: (!) [[/Discussion|Discussion]]
Посмотрите шаблон DefaultTemplate. Не используйте макрос <<Include()>> для автоматического выбора нужного языка (?). Почему? Потому что, если он будет использоваться на каждой странице, то сервер вики будет перегружен. Главная страница вики - единственное исключение из этого правила.
Disambiguation banner
Иногда наименование страницы может быть двусмысленным. Если этого нельзя избежать, Вы можете вставить что-нибудь подобное вверху страницы, чтобы подчеркнуть Ваше разъяснение:
Disambiguation : This page is about Debian Conferences. |
Код:
||<tablestyle="width:65%;margin-left:35%;padding-left:30pt" style="border:1pt solid #b48;border-left:5pt solid #d4a">'''Disambiguation :''' This page is about ''Debian Conferences''.<<BR>> For ''Debian configuration management system'', see [[debconf]].||
Debian "official material" banner
Часто, содержание некоторых страниц этой вики может быть также неплохо раскрыто в "официальной" документации Debian (или на других справочных ресурсах). Это хороший повод для сотрудничества - полезным будет добавить ссылку на соответствующую статью или заметку вверху страницы.
Образец ссылки на некую официальную страницу, связанную с текущей статьей
http://www.debian.org/somewhere - Sample topic
Код:
{{{#!wiki debian http://www.debian.org/somewhere - Sample topic }}}
Лицензию на логотип можно найти по ссылке Portal/IDB#debian-official-doc-modif-fpiat.
Table of Contents sections (содержание статьи)
Если статья обширна, вы можете добавить в нее таблицу с содержанием (Table of Contents). Образец можно посмотреть вверху этой страницы!
Код:
<<TableOfContents(2)>>
Раздел FAQ
Типичный FAQ может быть оформлен так:
- Q. Как я могу сделать XXXX?
- A1) Вы можете сделать XXXX, совершив X.
- A2) Вы можете сделать XXXX, попробовав Y.
Код (необходим пробел в начале строки):
Q. Как я могу сделать XXXX? :: A1) Вы можете сделать XXXX, совершив X. :: A2) Вы можете сделать XXXX, попробовав Y.
Footer sections (подвал)
Материал, который обычно располагается в "подвале" статьи, в самом низу страницы, может включать в себя:
- Раздел "See also" ("См. также")
- Ссылка на основную статью (если страница является подразделом другой статьи).
Categories, чтобы отметить связь с другими статьями
Credits для вложений
Page Fragments
Не только вики-код может быть многократно использован, содержание статей тоже! Если Вы хотите, чтобы нужный обрывок текста был повторен на других страницах, Вы можете использовать page fragment каждый раз. (Но не злоупотребляйте этим, дублируя контент повсюду!)
- Страница (page fragment), предназначенная для включения в другие статьи, должна быть соответствующим образом названа */!PageFragment/*
Добавьте скрытый комментарий (##) наверху, чтобы остальные пользователи поняли, что это заготовка (фрагмент).
Почитайте про макрос <<Include()>> в HelpOnMacros
Пример доступен по ссылкам InstallingDebianOn (статья куда вставлен фрагмент) и InstallingDebianOn/PageFragments/Philosophy (сам фрагмент). Вы также можете обратить своё внимание на то, как фрагмент вставляется в таблицу (но не используйте это в качестве обходного пути при форматировании с помощью moinmoin: смотри Complex Formatting).
Продвинутое форматирование/Complex Formatting
Избегайте продвинутое форматирование (использование таблиц, include, и т.д.)
- Это трудно для понимания и поддержки, как для Вас, так и для других вики-редакторов.
diff complex formatting сложно читать.
- Редактор с графическим интерфейсом может разрушить Вашу верстку.
Изображения, медиа-контент и другие вложения
Смотрите также: для moinmoin - HelpOnLinking.
Авторское право
Добавьте информацию об авторском праве внизу страницы, где Вы вставили изображение, таким образом:
## attachments: ## openlogo-100.jpg Copyright 1999 "Software in the Public Interest" from http://www.debian.org/logos/openlogo-100.jpg
Расположение
Лучше будет прикреплять изображение к родительской странице (а потом уже ссылаться на нее из других мест).
Для переведенных страниц прикрепляйте изображение к англоязычной версии (кроме локализованных изображений, например, с не-англоязычными надписями).
Скриншоты
Если Вы хотите вставить скриншот, возможно, стоит сохранить его на ресурсеhttp://screenshots.debian.net/, и тогда можно будет применить код:
[[http://screenshots.debian.net/screenshot/amide|{{http://screenshots.debian.net/thumbnail/amide|Screenshot|width=160}}]]
- Обратите внимание, что имя пакета дважды упомянуто в этом блоке кода.
Образец:
Расположение изображения
|
Можно сдвигать изображение вправо, используя CSS' float:right:
||<tablestyle="float:right; width:100px; background:transparent; margin: 0 0 1em 1em;" style="padding:0.5em; border-style:none;"> {{http://www.debian.org/logos/openlogo-nd-75.jpg}} ||
Важно: используйте width:100px.
"Work needed" теги
Тег - это пометка, которая имеет особое значение для сообщества. Его используют для группы страниц, для поиска по тегам и/или просмотра всех страниц, которые помечены этим тегом. Если используете MoinMoin, то необходимо применять Categories.
Используемые в данное время вики-теги:
Перечисленные теги относятся к т.н. Work needed.
Важно: не используете #deprecated, так как это мешает дальнейшему редактированию статьи (например, исправлению устаревших ссылок). Если Вы хотите, пометить страницы, нуждающиеся в улучшении/удалении, используйте в них соответствующие вики-теги.
Эти теги предназначены для вики-редакторов, не для посетителей, поэтому не делайте их навязчивыми; вместо того, чтобы вставлять предупреждающий тег в начало статьи, разместите его в подвале.
Статьи вики (страницы)
Требования к именам страниц и ссылкам
Используйте только формат CamelCase (в отличие от Underscore_Separated).
- Первая буква первого слова должна быть прописной.
- Избегайте специальных символов в именах.
Предназначение слешей состоит в создании групп связанных статей-подстатей (по принципу каталогов на компьютере). Если Ваша статья несомненно принадлежит некой совокупности, Вы можете создать ее как подстатью - см. пример в документации Moinmoin SubPages.
Для переведенных страниц смотрите Переводы.
- Подбор подходящего имени для статьи - это важный этап. Оно должно отражать содержание статьи и включать в себя слова, по которым посетители будут искать эту страницу.
- Избегайте двусмысленных имен - Не используйте, например:
- "Обзор"... обзор чего? Обзор Debian, сообщества, вики?..
- "Релиз"... это слово может иметь отношение к прошлому релизу, нынешнему стабильному релизу, к жизненному циклу релиза, будущему статусу релиза, процессу выпуска релиза, к команде, отвечающей за релиз, и т.д...
Создание статей
До создания статьи задайте себе несколько вопросов:
- На самом ли деле нужна новая статья? Может она уже существует под другим именем? Может быть, можно добавить содержание в какую-либо из ныне существующих статей?
Соответствует ли она требованиям wiki.debian.org?
Если сомнений нет, то вперед:
Выберите название статьи - см. Требования к именам страниц и ссылкам.
Найдите соответствующий портал по ссылке CategoryPortal (Вы можете найти больше, чем один, выберите тогда наилучший вариант)
- Сделайте ссылку с портала на созданную Вами страницу, потом перейдите по ней.
Выберите соответствующий шаблон (DefaultTemplate рекомендуется)
Если Ваша статья связана с чем-то, что уже частично описано в официальной документации Debian, разместите в самом начале ссылку на соответствующий документ (см. Debian "official material" banner)
- Когда статья будет готова, поставьте на нее ссылки с других страниц, с похожей тематикой (одной ссылки часто бывает достаточно).
- Еще пара-тройка советов:
- Перечитайте своё творение спустя два дня (оно всё еще кажется хорошим?)
- Оформите подписку на статью, чтобы быть в курсе всех изменений.
- Созданная Вами страница не является Вашей собственностью, так что не чувствуйте себя оскорбленным, когда другие люди захотят улучшить её.
Смотрите также: moinmoin's HelpOnPageCreation.
Переименование статей
Хорошие URIs не изменяются (w3). Всё же, иной раз необходимо переименовать статью, когда ее название не совсем точно отражает содержание.
До того, как Вы переименуете страницу:
Проверьте, чтобы эта страница не была в числе размещенных в CategoryPermalink.
Используйте Google (или другой поисковик), чтобы проверить, не ссылаются ли на статью какой-либо из сайтов вне этой вики. Ищите link:wiki.debian.org/FooBar. Если на статью ссылаются, подумайте дважды, прежде чем переименовывать её. Если всё же Вы переименовываете статью, то подумайте о создании страницы перенаправления и о том, чтобы связаться с автором стороннего ресурса с целью обновления ссылки на вики-статью.
Проверьте, есть ли страницы внутри вики, ссылающиеся на переименовываемую статью (для этого, откройте статью и кликните по ее заголовку, например, в нашем случае кликните вверху страницы по EditorGuide).
Если сомнений не осталось:
Выберите новое название. См. Требования к именам страниц и ссылкам.
- Удостоверьтесь, что обновили все вики-страницы, которые ссылались на старое название (для проверки, напишите предыдущее название в поиск вики, затем кликните "По тексту"!).
- Также позаботьтесь о переведенных версиях статьи.
Важно: Если переименовывание требует создания страницы перенаправления, то, возможно, идея сменить название плоха.
Удаление статей
Прочитайте Переименование статей, так как советы оттуда применимы и в данном случае.
Если Вы думаете, что страница должна быть удалена, Вы можете либо:
- Удалить статью сами (написав обоснование этому в поле для комментариев).
или Пометить статью тегом "CategoryProposedDeletion", чтобы другие редакторы смогли среагировать (поместите тег и объяснение в "подвале" страницы).
Не будьте несдержанными: не копируйте содержание существующих статей (с последующим их удалением) в какую-либо новую. Лучше посмотрите Слияние и разделение статей.
Опять же, если имеются переведенные версии, то удаляйте и их!
Слияние и разделение статей
Реорганизация вики - это хорошо. В следующих ситуациях:
- Слияние статей, описывающих одно и то же.
- Слияние нескольких статей, если все они чересчур маленькие.
Разделение обширной статьи, если она посвящена нескольким темам (возможно, в данном случае будет целесообразнее добавить элемент "содержание статьи" <<TableOfContents>> ).
По возможности сохраняйте историю работы над статьей:
- Используйте поле "Комментарий", чтобы описать изменения, произошедшие в результате слияний/разделений.
- При слиянии добавляйте информацию в одну из существующих страниц, не создавайте новую.
Для переводов: если Вы не можете слить/разделить страницы на других языках, оставьте комментарии для иноязычных редакторов, чтобы они могли сделать это сами.
Страницы перенаправления
В некоторых случаях, Вам, возможно, будет необходимо создать страницу перенаправления (которая автоматически перенаправит браузер по нужному адресу).
Не злоупотребляйте этим инструментом.
Код:
#redirect DestinationPage go to [[DestinationPage]]
Имейте ввиду, что #refresh не поддерживается в этой вики.
Смотрите также: moinmoin's HelpOnProcessingInstructions.
Категории
Помощь moinmoin wiki: using categories.
Список категорий, используемых в этой вики: CategoryCategory.
Порталы
Порталы - это узловые страницы, содержащие ссылки на статьи. Они образуют систему взаимосвязей внутри вики, вместе с категориями и поисковой машиной.
Порталы должны быть основаны на шаблоне портала PortalTemplate.
Создание порталов
Чтобы сделать из статьи портал, добавьте тег CategoryPortal в её подвал.
Не создавайте порталы, наполненные недействующими ссылками.
База данных изображений
Используемые сообществом иконки и логотипы порталов могут храниться в Portal/IDB. Это полезный инструмет для переводящихся на другой язык порталов и для создания единого оформления.
Переводы
В верхней части каждой статьи обычно есть ссылки к её вариантам на других языках - см. Headers section, а также можете посмотреть шаблон статьи DefaultTemplate.
Основы:
- У каждой статьи в этой вики может быть сколько угодно переводов, но всегда должен быть один "базовый" вариант.
- С целью упрощения работы языком базового варианта выбрана американская версия английского языка.
Переведенные статьи используют следующую схему именования "languagecode" + "/" + "EnglishName". Например:
Базовая версия: Hardware
Французский перевод: fr/Hardware
- Если Вы изменили перевод, обновите или прокомментируйте соответствующим образом и английскую версию тоже.
- Постарайтесь, чтобы основа, скелет статьи были одинаковыми во всех переводах, так как это упрощает синхронизацию (лучше всего, чтобы редакторы, не знающие Вашего языка всё же имели некоторые шансы найти и обновить нужный элемент).
- Если статья не имеет английского варианта, создайте его. Если Вы не знаете в достаточной мере английский, создайте вариант хотя бы с заголовком и ссылкой на Вашу страницу, чтобы быть уверенным в том, что она сохранится при появлении английской версии.
- Если страницы на Вашем языке еще не существует, создадите её путем копирования из английской версии, измените название, затем сделайте, как написано ниже.
Синхронизация переводов
Это когда Вы обновляете статью для соответствия с другими языковыми версиями (т.н. "синхронизация" версий),
- Все версии статьи должны иметь единый скелет, основу (форматирование, расположение параграфов и т.д.).
- Чётко отражайте статус синхронизации:
- либо сразу же изменяйте страницу целиком, и затем изменяйте количество языковых вариантов в заголовке
либо добавьте комментарий в духе ## TRANSLATION UPDATE STOPPED here на том месте, где остановились.
- Если перевод новее, чем английский вариант:
- либо обновите English-версию сами, если можете (не беспокойтесь о мелких ошибках - кто-нибудь исправит их)
либо поставить тег "UpdateEnglish" в самый низ страницы, затем добавьте "+ IMPROVEMENTS" в комментарий к английской версии.
Переводчики вики
Участники, вовлеченные в перевод статей вики Debian, могут добавить тег CategoryWikiTranslator на свою домашнюю страницу.
Помощь wiki.debian.org
Вы можете улучшить wiki.debian.org:
- Добавлять содержание в любую статью, где можете.
- Добавлять свои замечания и вопросы в конец любой статьи, которую посещаете.
- Исправлять орфографию.
Переводить статьи.
Находить и исправлять статьи по тегам ?HelpWanted, FixMe и ToDo.
Реорганизовывать вики.
- Делиться своими знаниями об установке и использовании Debian
- Если Вы не работаете в IT, Вы можете создавать статьи о том, как Вы используете компьютеры в своей ежедневной работе. Поделитесь своими проблемами и нуждами.
Debian нужна помощь не только в IT-области, но и в других сферах (в юридической сфере; маркетинге; организации мероприятий; сборе средств; связях с общественностью и многое другое). Смотрите также Как помочь Debian?.
Продвижение wiki.debian.org
Наилучший и простейший способ популяризировать эту вики - это использовать её самому и делать ее полезной для других, поддерживая и добавляя полезные статьи (помните о требованиях к контенту).
Если Вам задали вопрос в листе рассылки, на форуме или на IRC-канале,
- первым делом и лучше всего будет справиться в официальной документации Debian (www.debian.org/* , man руководства, README и т.д.), предлагая уточнения авторам и майнтенерам, если необходимо;
- во-вторых, дополнить соответствующую вики-страницу, чтобы она отвечала на поставленный вопрос, и направлять пользователей туда.
Часто задаваемые вопросы (FAQ)
- Q) Могу я получить список всех страниц этой вики?
A) Да, смотрите TitleIndex.
- Q) Может, чтобы улучшить вики, стоит коренным образом реорганизовать её?
- A) Возможно, но реструктуризованная вики может создать множество трудностей. Гораздо более важно наполнить нынешний её вариант полезным содержанием.
- Q) Есть какой-нибудь способ вывести список статей-сирот (статьи без ссылок на них)?
A) Нет (OrphanedPages не работает; ссылки в виде [[PageName|Link Label]] в счёт не идут). Но существование сирот представляет собой проблему только в том случае, если есть страницы, которые должны ссылаться на них, но не ссылаются (тогда исправьте это), или если статья-сирота не показывается в результатах поиска (тогда убедитесь в том, что она включает в себя соответствующие ключевые слова, и без ошибок).
- Q) Как я могу отслеживать изменения?
- A) Используя два способа, представленные на верхней панели:
ссылка на страницу RecentChanges (отслеживание изменений ограничено неделей для обычных посетителей, 90 днями для залогинившихся пользователей);
- подписка на статьи, после оформления которой будут отправляться уведомления на Вашу почту после каждого изменения статьи.
Техническая информация
Эта вики запущена на ПО moinmoin, версия 1.9 (Системная информация). На данный момент всё запущено на оборудовании, предоставленном Dembach Goo Informatik GmbH & Co KG (и железо, и хостинг, и канал).