РУКОВОДСТВО ПО РЕДАКТИРОВАНИЮ ВИКИ
Эта статья предназначена для людей, желающих редактировать вики 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" (смотрите также)
Ссылка на "Parent Page : ?ParentPageName" (если страница является подразделом другой статьи).
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.
Используемые в данное время вики-теги:
Важно: не используете #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:
- Добавить содержание в любую статью, где может.
- Добавить свои замечания и вопросы в конец любой статьи, которую посетит.
- Исправить орфографию.
Переводить статьи.
ReFactor anything you can.
Cleanup (see ThreadMode)
- Pass on your knowledge on how to install or use Debian
- If you don't work in IT, you can create a page to explain how you use computers in your day-to-day work. Explain your problems and needs.
Debian also needs non-IT skills (legal; marketing; organizing events; fund-raising; public relations; and much more). See also http://www.debian.org/intro/help.
Promoting wiki.debian.org
The best and easiest ways to promote this wiki are to use it yourself and to make it useful to others by contributing useful material (bear in mind the content guidelines).
When you are asked a question in a mailing list, forum, or irc channel,
- the first and best option is to point inquiries towards the official Debian documentation (www.debian.org/* , man page, README, etc.), suggesting improvements to the author or maintainer if necessary;
- the second best is to update the appropriate wiki page to make sure it answers the question, and point towards that.
Frequently Asked Questions
- Q) Can I get a list of all the pages on this wiki?
A) Yes, see TitleIndex
- Q) Wouldn't the wiki be more useful if it was better organized?
- A) Possibly, but a structured wiki is largely a contradiction in terms. It's more important to give it good content.
- Q) Is there a way to show just the orphan articles?
A) No (OrphanedPages is broken; links in the form [[PageName|Link Label]] aren't counted). But being an orphan is only a problem if there are pages that should link to it and don't (so fix those), or if the page fails to show up in searches (so make sure it includes the appropriate keywords).
- Q) How do I keep track of changes?
- A) By using two features accessible via the sidebar menu:
the link to the RecentChanges page (limited to a week for visitors, 90 days for logged-in users);
- the Subscribe option, which requests e-mail notification when the page is modified.
Technical Information
This Wiki is running moinmoin software, version 1.9 (wiki configuration information). It currently runs on a machine sponsored by Dembach Goo Informatik GmbH & Co KG (both hardware, housing and bandwidth). tablestyle="width:100%;" style="width:32px;border-color:#ff9ec2"