Политика стиля Wiki

Материал из Mandriva Russian Community Wiki

Перейти к: навигация, поиск
Это черновой вариант страницы. Она требует улучшений.
Если вы хотите внести свой вклад, просто нажмите на вкладку править . Посмотрите другие страницы для улучшения и поддержки.

Эта политика предназначена для определения общей политики редактирования статей Wiki Mandriva Linux. Помимо этого, она будет содержать в себе шаблоны и стили, которые могут применяться и должны применяться, когда это необходимо. Она рассматривает иерархию и формат wiki, общее редактирование niceties и другую полезную информацию.

Если вы собираетесь заниматься поддержкой и редактированием документов этой wiki, эта страница обязательна для чтения!

У каждого есть свой стиль. Мы смотрим на это как на написание письма, как на написание спецификации к файлу и как на статьи, написанные в предыдущих TWiki. Мы ценим индивидуальный стиль! Как было сказано выше, когда речь идет о сохранении документов, написанных кем угодно и о чтении их многими людьми, согласованность делает wiki на вид более профессиональной. Это также приведет к большему порядку, к меньшему дублированию контента, и к более приятному получению «опыта».

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

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

  • У кого есть время подписаться на YAML (еще один список рассылки). Isn’t that the purpose of a Wiki (discussion page [currently almost empty], voting processess if needed etc.)? --nbrouard 09:53, 7 June 2007 (CEST)
  • web-discuss is a ml with very few messages, but writing in the Discussion page is ok. Olivier FAURAX 11:42, 25 August 2007 (CEST)

Содержание

Изменение страниц

Описывайте свои изменения

Напишите вкратце произведённые изменения в небольшом поле рядом с полем редактирования. Вы можете использовать сокращения, чтобы описать изменения, как это описано в карте изменений.

Прежде чем сохранить, воспользуйтесь Предварительным просмотром

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

Подписывайте свои комментарии в страницах обсуждений

На странице обсуждения подпишите свой сообщение написав четыре тильды: ~~~~

Вам необходимо «подписать» ваши комментарии на странице обсуждения:

  • Три тильды (~~~) установит ваше имя: Karl Wick
  • Четыре тильды (~~~~) установит ваше имя, а также дату и время: Karl Wick 07:46, 27 November 2005 (UTC)
  • Пять знаков тильды (~~~~~) установит только дату и время: 07:46, 27 November 2005 (UTC)

Плоский макет документа

На этой wiki нет иерархии, это значит, что:

  • Заголовок страницы — это имя
  • Избегайте использовать {{title}}, так как оно не рассматривается как заголовок в системе поисковика.
  • Для группировки страниц используйте категории и семантические расширения

Не делайте: 

Title : Releases/Mandriva/2009/Errata
{{title|Mandriva 2009 Errata}}
This is the errata of Mandriva 2007

Но: 

Title : Mandriva_2009_Errata
[[Category:Errata]][[Category:2009]]
This is the errata of Mandriva 2009

Для заголовка символ '_' и ' ' эквивалентны. Этот пример можно улучшить с использованием семантического расширения : … of Mandriva [[version:=2009]]…

Выбор заголовка

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

  • кратким, недвусмысленным. Подумайте, как бы будете обращаться к нему с других страниц (…, прочитайте [[Список известных проблем Mandriva Linux 2009]]….)
  • содержать 'Mandriva' + номера релизов ТОЛЬКО для специфичных релизов. Не используйте «Виртуализация в Mandriva 2009», если она применяется ко всем выпускам Mandriva. И потом, не используйте «Виртуализация в Мандрива», очевидно что речь на wiki идет о Mandriva. Достаточно — «Виртуализация».
  • предоставлять теме целую страницу

Как придумать хороший заголовок? Подумайте, что вы наберете в google для поиска этой страницы.

Хорошая практика

Для системы поиска

  • не используйте '=' для выделения заголовков раздела, начните с '==' : при ковертировании в html, MediaWiki преобразует h2 в h1, сделает заголовок страницы единственным большим заголовком. Таблица содержимого автоматически поймет это.
  • для новой страницы, сделайте ссылку на другую страницу wiki (если вы не нашли подходящей, воспользуйтесь персональной страницей). Это позволит обнаружить страницу системе поиска, а также другим лицам, кто воспользуется ссылкой на неё.
  • для новой страницы, добавьте подходящую категория в начало : тем самым пользователи будут предупреждены, о том, что это новая страница.

Для удобочитаемости

  • одна тема на статью: не создавайте статью о «Графических программах» на которой вы подробно объясняете Gimp, Inkscape и т. д. Создайте по одной странице на каждую программу и сошлитесь на них из основной статьи. Помощью послужит первоначально создание содержания документа.
  • постарайтесь разместить одну секцию раздела или подраздел на экран: это облегчит чтение.
  • не пытайтесь использовать цвета и формы по своему усмотрению. На этой wiki, за исключением Заглавной страницы и подобных ей, все страницы должны придерживаться одного цвета и формы. В случае использования желаемого вами цвета текста, в будущем при смене CSS это будет выглядеть ужасно или приведет к непредсказуемому результату (попробуйте : попробуйте воспользоваться ссылкой в {{title}} = голубая ссылка на голубом фоне).

Для совместной работы

  • создайте ссылку на не существующую страницу (… для этого нужно написать [[IPv6]] …, когда страницы IPv6 не существует) : это позволит определить список нужных страниц в списке требуемых страниц.
  • не колеблясь создавайте страницы из 5 строк: это послужит началом совместной страницы. Люди меньше боятся продолжить страницу, нежели её создать.
  • начните с содержания: в то время, как вы обдумываете раздел, люди поймут что вы хотели сделать и начнут заполнять секции.
  • ссылаясь на статью, не ссылайтесь на раздел или подраздел: ссылка на RPM_Tutorial#from_sources станет не рабочей, если раздел будет переименован в RPM_Tutorial#from_upstream_sources.

Макет раздела (Topic Layout)

Макет раздела или тематическая иерархия — это очень важно. Все должно быть размещено в логическую иерархию, в этом есть смысл. Это не только позволит проще искать, но также предоставит не плохой макет дерева, который позволит просматроивать wiki проще.

Существуют ряд верхних узлов :

  • Документация — этот узел для документации конечного пользователя
  • Политики — это узел для политик Mandriva
  • Разработка — этот узел для всего связанного с разработкой
  • Релизы — этот узел для информации о релизах Mandriva Linux, который включает в себя заметки о релизе, список известных проблем, а также разработанную информацию относящуюся к релизу
  • Инструменты — этот узел для большинства инструментов, разработанных Mandriva
  • About — этот узел для различных сведений в целом о Mandriva
  • Community — community-related information for things such as parties, events, links to other community sites, etc.
  • Проекты — this node is for Mandriva projects that can encompass many tools, releases. etc. (such as «easier wireless configuration» would be a project whereas «drakroam» would be a tool)
  • Web — this node is for Mandriva web-related products, projects, and development

These top-level nodes are further broken down into various sub-nodes. For instance, the Releases top-level node logical has the various Mandriva versions below it. So the first sub-node is the name of the product, be it Mandriva, Mandrake, or Corporate. Below that would be the version number, 2007, 3.0, etc. This node would be the «main page» for that release; for example: Releases/Mandriva/2007.

While that sub-node contains short information pertaining to a release, there is far too much information per release to contain it all on one page. To that end, there are more sub-nodes below the release, such as «Errata» and «Notes» and «Development»:

We can even go further with the «Development» sub-node, into other nodes such as «Changelog» for a changelog of changes for this version and «codename» or beta/RC name/number for information for a particular release. For instance:

It should be evident that there is a logical progression of nodes or leaves that corresponds to it’s parent node. In this manner, anyone looking for release information on Mandriva 2007 will know that it can be found in the Releases node and can navigate further from there.

If you’re unsure of how the nodes should be created, look at existing content or ask before creating a new node.


However, the topical hierarchy has a big downside, making pages titles difficult to read or understand, and unrelated to the document main word it should be indexed with by search engines. Furthermore, it requires a 'title' template so that a readable title is available in the document.

We are going to rewrite this policy document, so that the contents layout is totally flat, hierarchy and structure appearing in categories and semantics usage; the existing topical hierarchy will then likely appear in categories and sub-categories.

Please join the web-discuss mailing-list about that. This is still a work in progress.

Style and Templates

Style and how documents are written are extremely important. Some people use wiki syntax, some people prefer to use HTML syntax. Some people create page names such as «System Administration» while others would use CamelCase or short names such as «SysAdmin» or «SystemAdministration».

Some people will make use of paragraph tags when it’s not required, others will use line break tags when there is no need, etc. Some people prefer excessive bolding and italics. These are all things that need to be «normalized» so that the layout and look of content is consistent from page to page.

Templates

MediaWiki allows for the use of templates, which provide consistent styling to text we are trying to mark up or have stand out. Templates are written using:

{{template|text}}

So to use the title template to bring emphasis to the description or name of the page, use:

{{title|This is the title of the page}}

The following templates are available and must be used:

  • Template:title — the title template is used as the very first element of the page to describe the contents of the page
  • Template:version — a template to highlight a version number; this should be used only for Mandriva release version numbers (i.e. Mandriva Linux 2007)
  • Template:file — a template to highlight filenames and directory names (i.e. /etc/ssh/sshd_config)
  • Template:cmd — a template to highlight a quick command that does not need to be wrapped in <pre> tags, such as urpmi --auto-select; typically used within a paragraph and not standalone
  • Template:media — a template to highlight an urpmi medium name that does not need to be wrapped in <pre> tags, such as /main/release; typically used within a paragraph and not standalone
  • Template:prog — a template to highlight the name of a program being mentioned (not the name of a program as it’s being used, but as it’s being referenced); this should only appear once in a paragraph (the first time it’s mentioned) (i.e. sshd)
  • Template:pkg — a template to highlight an rpm package name (i.e. openssh-server)
  • Template:menu — a template to highlight a series of menu clicks (i.e. File->Save)
  • Template:var — a template to highlight variable names, like bash or perl, etc. (i.e. $HOME)
  • Template:macro — a template to highlight rpm macros and other «%*» constructs in spec files (i.e. %install or %mklibname)
  • Template:olang — a template to create a link to similar topics in other languages (see Home and Fr/Maison for an example of how to use this)
  • Template:bug — a template to create a quick link to bugzilla with the little bug icon in front of it (i.e. {{bug|12345}} would look like Изображение:bug_small.png ошибка #12345)

These templates exist to be used and should be used consistently and in the manner noted above. They are used to provide visual queues as to things being discussed and to allow things such as file or package names to stand out, making them easier to distinguish.

Note: If a template has to contain the equal sign (=) or the pipe symbol (|) it won’t work unless the «=» or "|" are escaped with the tags <nowiki> and </nowiki>

Style

Here are a few items that should be paid attention to in regards to the style of an edited page:

  • There is no need to use paragraph <p> tags; just insert a blank line between paragraphs and the wiki will auto-format; likewise try to avoid <br> tags as well
  • Try to avoid using the wikitext notation for bold and italic (''' and '' respectively); instead use the HTML codes (<b> and <i> respectively); using the HTML codes is preferred as it is much easier to see when editing what styling is being applied
  • Spacing between header tags is important; there should be exactly 1 blank line preceeding them (the style-sheets help to provide adequate spacing, so extra spaces will only serve to enlarge it too much)
  • Do not put links to other pages within a header; links to other pages belong in text, not in headers
  • Do not use headers as «highlighters» or for creating a list; headers automatically create a table of contents and should be used to separate logical sections of text, not to create formatted lists
  • When linking to another article on the wiki, please do not use the full path of the wiki, but instead use [[Policies/Wiki_Style|Wiki Style]] (instead of, for instance [http://wiki.mandriva.com/Policies/Wiki_Style Wiki Style] as that will keep everything consistent even with domain name changes and so forth
  • Please do not use <a href=...> in pages, use the standard [http://foo some text] notation instead
  • There should be 1 blank line separating blocks of text; this makes the text easier to read when editing; so please ensure there is 1 blank line between paragraphs, between paragraphs and <pre> tags, lists, etc.

Inter-Wiki Links

You can use Inter-Wiki links to link to other languages on the wiki and to external sites, such as Bugzilla. For instance, using:

[[:bugz:12345]]

Will link to http://qa.mandriva.com/show_bug.cgi?id=12345 automatically. You can pretty this up if you like by using [[:bugz:12345|Bug #12345]] otherwise the link will look like this: bugz:12345. This is using the «bugz» inter-wiki name to represent the Bugzilla url. You can instead opt to use the fancier {{bug|12345}} template instead, however if you want to use your own text but retain the link, it’s better to use the inter-wiki link as the bug template gives you no opportunity to create your own link name (i.e. [[:bugz:12345|This was a nasty bug]]).

Where inter-wiki links are available, please use them. This way if a URL ever changes down the road (i.e. bugzilla is no longer available at http://qa.mandriva.com) it’s a matter of changing one record in the inter-wiki database table and one template as opposed to potentially hundreds of individual links.

Likewise, the olang template uses the same inter-wiki linking. To link a page to the French version of that page, you would use the olang template with the inter-wiki link inside of it like this:

{{olang|[[:fr:Maison|French]]}}

Here the «fr» inter-wiki name is specifying the french version of the page, called «Maison» in this case. This would take you to /Fr/Maison on the site; ie: fr:Maison. Currently supported language-spaces are:

  • de — German
  • es — Spanish
  • fr — French
  • ja — Japanese
  • nb — Norwegian

Though it’s simpler to just add the l10n interwiki this way:

[[fr:Maison|French]]

which will make mediawiki place them in a special place.

Syntax

Here are some links regarding wiki syntax and the types of things you can do with MediaWiki:

Starting a New Page

Before starting a new page, be sure you have searched carefully first before creating the new page. Chances are, the topic already exists and should be edited, rather than duplicated.

If you need to create a new page, be aware of it’s place in the «tree» according to the rules noted in the Topic Layout. If you create a page incorrectly, or create top-level page, someone will either have to delete or move it, which does nothing but frustrate you and create extra work for someone else.

Other good ideas to note can be found on Wikimedia’s Starting a new page topic.

Removing or Renaming Pages

Please don’t remove or rename pages on your own. If you feel that a page is in a spot where it does not belong, please email the web-discuss-mailinglist with your request and one of the site administrators will perform the page move and/or deletion if it is required.

For the administrators, Wikimedia has some good information:

Talk Pages

Talk pages are an excellent resource. With TWiki, user comments were placed inside the document itself (such as a changelog of who did what, etc). With MediaWiki this is not only not required, but discouraged. User comments on a page detract from the contents of the page itself, making it look dirty and clumsy. Talk pages should be used instead (Talk pages are also known as Discussion pages). These pages can contain a changelog of who made what changes, and they can also contain user comments on the topic, requests for additional information, and so forth. Talk pages are the «drawing board» behind the real content.

Unlike TWiki, there is no need to maintain a «changelog». If, when you are editing a page, you place something in the summary field (i.e. what you did or changed), then anyone viewing the history of the page will not only see your name, but what you put in the summary field (your changelog «entry»), and when you made the change.

Please also refer to Policies/Wiki_Style/Example for an example document that illustrates all of the markup discussed here.

Extensions

We are discussing (on wiki-discuss) the inclusion of several extensions that could help:

  • video/media inclusion plugin (Under discussion. Requirements : able to play theora files, videos should be viewable with Mandriva Free edition)
  • At least the following extensions are mandatory for any mediawiki site, CharInsert.php for MediaWiki:Edittools and Expr.php and ParserFunctions for many recent templates needing the #if conditions: 
require_once( "extensions/CharInsert.php"); in you LocalSettings.php
require_once( "extensions/Expr.php");
require_once( "extensions/ParserFunctions.php");

You can watch the installed extensions at Special:Version. And they are currently not here 16:49, 14 August 2007 (CEST).

Источник — «http://wiki.mandriva.com/ru/%D0%9F%D0%BE%D0%BB%D0%B8%D1%82%D0%B8%D0%BA%D0%B0_%D1%81%D1%82%D0%B8%D0%BB%D1%8F_Wiki»
Fund the Mandriva Linux project
На других языках
Looking for a job?