| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| ru:wiki:wikirules [2018/05/22 02:13] – [Мантры] sem5959 | ru:wiki:wikirules [2018/05/22 05:43] – [Мантры] sem5959 |
|---|
| |
| |
| Следующие стандарты должны помочь поддерживать совместимость wiki, легко понять для новичков и легко редактировать для случайных участников. | Следующие стандарты должны помочь поддерживать совместимость wiki, легко понять для новичков и легко редактировать для случайных участников.. |
| |
| В некоторых случаях могут быть исключения, когда это имеет смысл, но для этого должна быть веская причина. | В некоторых случаях могут быть исключения, когда это имеет смысл, но для этого должна быть веская причина. |
| |
| ====== Wiki contribution guide ====== | ===== Мантры ===== |
| | - **Статьи должны быть легко читаемыми и легко редактировать, проще.** Статьи должны быть отформатированы только с использованием основных функций, найденных в графическом интерфейсе редактора , а также при необходимости использовать тег кода и таблицу. \\ Зачем? Более продвинутое форматирование придаст этой вики более «профессиональный» вид, но также будет труднее читать и редактировать для случайных пользователей и вкладчиков. Более продвинутые макеты с вкладками и кнопками более компактны, но, как правило, более сбивают с толку, чем простой макет с одним списком действий и ссылок, где читатели просматривают и щелкают. Также простой неинтерактивный макет позволяет легко печатать. Например, посмотрите на это руководство. [[docs:guide-quick-start:factory_installation|Первоначальная установка LEDE на устройстве]].\\ \\ |
| | - **Избегайте дублирования информации в этой вики** : информация по той же теме должна появляться в вики только **//один раз//**. Если это необходимо в другом месте, мы ссылаемся на него со ссылкой!\\ Например, если вы пишете учебник, и один из шагов - «настроить USB-хранилище», вы должны указать ссылку на [[docs:guide-user:storage:usb-drives|Использование устройств хранения]]. Не записывайте (или не копируйте) те же процедуры в новом учебнике! \\ \\ |
| | - **Избегайте дублирования исходной документации** : рассмотрите возможность включения более общих частей документации в **//вверх//**, по **течению** и просто ссылку на статью в вашей статье. Эта вики существует для документации, связанной с OpenWrt, например [[docs:guide-user:network:ipv4:start]]. Некоторые примеры upstream wikis: i.e. [[https://wireless.wiki.kernel.org/|Linux WiFi drivers wiki]], [[https://community.openvpn.net/openvpn/wiki|OpenVPN Wiki]] и.т.д. Не все используют вики, и не все принимают вклады от третьих лиц. Если восходящие взносы невозможны, то это прекрасно, чтобы иметь эту информацию в вики OpenWrt. \\ \\ |
| The following standards should help keeping the wiki consistent, easy to understand for newbies, and easy to edit for casual contributors. | - **Информация о версии**: информация в статьях должна быть действительной для **//текущей стабильной версии//**. Информация, относящаяся **только** к более старым или моментальным снимкам (как устаревшим, так и очень новым), должна быть отмечена как таковая. \\ \\ |
| | - **Статьи должны быть легкими, чтобы найти** что большинство людей будут искать информацию в поисковой системе по своему выбору или с собственным внутренним поиском вики. Используйте короткие, описательные заголовки и введения, содержащие правильные ключевые слова, которые можно найти. Вы можете попытаться найти свою статью с помощью своей любимой поисковой системы (через несколько дней вы отправили статью, потому что поисковым системам нужно время для обновления своих индексов). Если вы не найдете свой собственный контент, другие, вероятно, тоже не будут! \\ Например**installing.opkg.packages.in.mount.point.other.than.root** длинный заголовок , который может быть заменен на что - то вроде opkg - Направления по установке, но последнее не будет так легко найти, как первое, когда кто-то не просматривает вики, но вместо этого использует поисковую систему. \\ \\ |
| There can be exceptions in some cases where it makes sense, but there should be a good reason for that. | - **Статьи должны объяснять, почему они существуют, какова их цель**. Пожалуйста, добавьте параграф «введение» или два, где вы объясните, какая функция вы настраиваете, и какие потребности могут быть удовлетворены, следуя инструкциям. Это не должно быть очень многословным. Например, первый абзац здесь: [[docs:guide-user:additional-software:imagebuilder|Использование генератора изображений (Image Builder)]] \\ \\ |
| | - **Статьи должны содержать информацию VERIFIABLE, спекуляция должна быть четко обозначена как таковая **. Действительно, это очень важно в любой вики. Укажите источники для утверждений, которые не являются общеизвестными, или пишите достаточно информации, чтобы можно было легко искать источники в Google. Например: [[docs:guide-user:network:wifi:usb3.0-wifi-issues|проблемы с USB 3.0 и WiFi]] \\ \\ |
| ===== Mantras ===== | - **Все учебники, которые вы пишете, должны быть протестированы лично или должны иметь предупреждение** о том, что при написании их невозможно провести тестирование (и удалить предупреждение, когда кто-то его успешно протестировал). \\ \\ |
| - **Articles must be easy to read and easy to edit, simpler is better.** Articles should be formatted only using basic features found in the editor GUI, plus the code tag and table construct where necessary.\\ Why? More advanced formatting would give this wiki a more "professional" look, but it will also be harder to read and edit for casual users and contributors. More advanced layouts with tabs and buttons are more compact but are usually more confusing than a simpler layout with just a single list of actions and links where readers scroll through and click. Also a simple non-interactive layout allows easy printing. For example, look at this tutorial [[docs:guide-quick-start:factory_installation|Factory install: First-time installation of LEDE on a device]].\\ \\ | - **Одна тема в каждой статье**. Статьи должны быть сосредоточены на одной, сфокусированной теме, например, "**установка и настройка Adblock**". Общие статьи, охватывающие множество разных тем, например "**фильтрация веб-трафика**" (где вы говорите об Adblock, прокси-серверах и, возможно, Tor и VPN), должны быть разделены. \\ \\ |
| - **Avoid duplicating information within this wiki** : Information on the same topic shall appear in the wiki only **//once//**. If it is needed somewhere else, we refer to it with a link!\\ For example if you are writing a tutorial and one of the step is "configure USB storage" you should link to [[docs:guide-user:storage:usb-drives|Using storage devices]]. DO NOT write down (or copy-paste) the same procedures in your new tutorial! \\ \\ | |
| - **Avoid duplicating upstream documentation** : consider contributing the more generic parts of the documentation to **//upstream//**, and just link to that in your article. This wiki exists for OpenWrt-related documentation, for example [[docs:guide-user:network:ipv4:start]]. Some example upstream wikis: i.e. [[https://wireless.wiki.kernel.org/|Linux WiFi drivers wiki]], [[https://community.openvpn.net/openvpn/wiki|OpenVPN Wiki]] etc. Not all employ wikis, and not all accept contributions from third parties. If upstream contributions are impossible, then it's fine to have that info in the OpenWrt wiki. \\ \\ | |
| - **Versioning information**: the information in the articles should be valid for the **//current stable release//**. Information that applies **only** to older or snapshot releases (either deprecated or very new features) should be marked as such. \\ \\ | |
| - **Articles should be easy to find** most people will search for information with the search engine of their choice, or with the wiki's own internal search. Use short, descriptive titles and introductions that contain the right keywords to be found. You can try to search for your article with your favorite search engine (after a few days you posted the article, because search engines need time to update their indexes). If you won't find your own content, others probably won't as well!\\ E.g. **installing.opkg.packages.in.mount.point.other.than.root** is a long title that could be replaced with something like //opkg -- Installation Destinations//, but the latter will not be as easily be found as the first one when someone does not browse the wiki, but uses a search engine instead. \\ \\ | |
| - **Articles should explain why they exist, what is their goal**. Please add an "introduction" paragraph or two where you explain what is the feature you are configuring, and what needs can be satisfied by following the instructions. It does not need to be very verbose. For example, the first paragraph here: [[docs:guide-user:additional-software:imagebuilder|Using the Image Generator (Image Builder)]] \\ \\ | |
| - **Articles should contain VERIFIABLE information, speculation should be clearly labeled as such**. Really, this is very important in any wiki. Cite sources for statements that aren't common knowledge, or write enough information to allow easy google searching for sources. For example: [[docs:guide-user:network:wifi:usb3.0-wifi-issues|USB 3.0 and WiFi problems]] \\ \\ | |
| - **All tutorials you write must be tested personally or must have a warning** stating that testing was not possible when writing them (and to remove the warning when someone successfully tested it). \\ \\ | |
| - **One topic per article**. Articles should be focused on a single, focused topic, for example "**installing and configuring Adblock**". General articles that span many different topics, for example "**filtering web traffic**" (where you talk of Adblock, proxy servers, and maybe Tor and VPNs) should be split up. \\ \\ | |
| - **Large tutorials should be split up**. Large tutorials where each step is long should be split up in separate articles, each covering a part of the steps. This is even more important if the tutorial contains conditional or optional steps (for example: "do step **A**, then you can do either step **B** or **C**, then do **D**"). For example [[docs:guide-quick-start:factory_installation|Factory install: First-time installation of LEDE on a device]] or this [[docs:guide-developer:helloworld:start|"Hello, world!" for LEDE]] \\ \\ | - **Large tutorials should be split up**. Large tutorials where each step is long should be split up in separate articles, each covering a part of the steps. This is even more important if the tutorial contains conditional or optional steps (for example: "do step **A**, then you can do either step **B** or **C**, then do **D**"). For example [[docs:guide-quick-start:factory_installation|Factory install: First-time installation of LEDE on a device]] or this [[docs:guide-developer:helloworld:start|"Hello, world!" for LEDE]] \\ \\ |
| - **Articles should be accessible from within the wiki** Please make sure your article has a link in one of the main Categories pages (links below) if it is some kind of tutorial. Some articles may not need this if they are part of a multi-article tutorial, but again make sure ALL articles can be reached either from the main Categories pages or from the other pages of its multi-article tutorial. Very popular articles will also be linked from within other tutorials, as explained in the **Avoid duplicating information within this wiki** mantra above. For a handy list of pages linking to the current page, click on the "**chain**" icon you find on the right tool panel (it's under the **clock** icon). \\ \\ | - **Articles should be accessible from within the wiki** Please make sure your article has a link in one of the main Categories pages (links below) if it is some kind of tutorial. Some articles may not need this if they are part of a multi-article tutorial, but again make sure ALL articles can be reached either from the main Categories pages or from the other pages of its multi-article tutorial. Very popular articles will also be linked from within other tutorials, as explained in the **Avoid duplicating information within this wiki** mantra above. For a handy list of pages linking to the current page, click on the "**chain**" icon you find on the right tool panel (it's under the **clock** icon). \\ \\ |
| |
| ===== Structure ====== | ===== Состав ====== |
| To give the Wiki a better structure, we employ ''namespaces'' and ''categories'' (and ''tags''): | Чтобы дать Wiki лучшую структуру, мы используем ''namespaces'' and ''categories'' (and ''tags''): |
| * **Namespaces** are highest. In each of these upper namespaces, there shall be a maximum of 3 (three) sublevels. | * **Пространства имен** самые высокие. В каждом из этих верхних пространств имен должно быть не более 3 (трех) подуровней. |
| * //[[about:|about]]// about the OpenWrt project in general | * //[[about:|about]]// проекте OpenWrt в целом |
| * //[[toh:|TOH]]// documentation about supported devices, called "Table of Hardware". | * //[[toh:|TOH]]// поддерживаемых устройствах под названием «Таблица оборудования». |
| * //[[packages:|Packages]]// documentation about available packages | * //[[packages:|Packages]]// документация о доступных пакетах |
| * //[[:downloads:|Downloads]]// landing page to download firmware for your device | * //[[:downloads:|Загрузка]]// целевой страницы для загрузки прошивки для вашего устройства |
| * //[[docs:|Documentation]]// main documentation page | * //[[docs:|Документация]]// главной страница документации |
| * //[[wiki:|Wiki]]// pages about wiki functionality and wiki contribution rules | * //[[wiki:|Wiki]]// страницы о функциях wiki и правилах внесения вики |
| * //[[faq:|FAQ]]// is the place for FAQ lists | * //[[faq:|FAQ]]// этот список часто задаваемых вопросов |
| | |
| * **Categories** provide the first level of the namespaces. They distinguish different kinds of **docs**: | |
| * //[[docs:guide-quick-start:begin_here|Quick Start]]// quick start tutorials, used for first installation and setup, or similar. | |
| * //[[docs:guide-user:|User Guide]]// most of the documentation for users goes here | |
| * //[[docs:guide-developer:|Developer Guide]]// developer documentation | |
| | |
| * **Tags** are different. While the structure is exclusive, you can place an article only in one subcategory, tags are more flexible. More of them can be placed simultaneously in one article, and thus allow for a more flexible categorizing. To reproduce this with the structure we could write symbolic articles, which are placed in different subcategories and redirect to one article. But let's not do that. Tags will prove most useful, when you want to search for routers with certain features. | |
| * [[meta:tags]] Overview | |
| | |
| **Sidebar** | |
| To ease navigation, we use a sidebar, in two places to "animate" it, show more or less links depending on where you have clicked. Any change should be mirrored in both files (if relevant). | |
| * //[[docs:sidebar|Sidebar for Docs section]]// | |
| * //[[sidebar:|Sidebar for general section]]// | |
| ===== Structure ====== | |
| To give the Wiki a better structure, we employ ''namespaces'' and ''categories'' (and ''tags''): | |
| * **Namespaces** are highest. In each of these upper namespaces, there shall be a maximum of 3 (three) sublevels. | |
| * //[[about:|about]]// about the OpenWrt project in general | |
| * //[[toh:|TOH]]// documentation about supported devices, called "Table of Hardware". | |
| * //[[packages:|Packages]]// documentation about available packages | |
| * //[[:downloads:|Downloads]]// landing page to download firmware for your device | |
| * //[[docs:|Documentation]]// main documentation page | |
| * //[[wiki:|Wiki]]// pages about wiki functionality and wiki contribution rules | |
| * //[[faq:|FAQ]]// is the place for FAQ lists | |
| |
| * **Categories** provide the first level of the namespaces. They distinguish different kinds of **docs**: | * **Категории** обеспечивают первый уровень пространства имен. Они различают различные виды **документов**: |
| * //[[docs:guide-quick-start:begin_here|Quick Start]]// quick start tutorials, used for first installation and setup, or similar. | * //[[docs:guide-quick-start:begin_here|Краткое]]// руководство по быстрому началу работы, используемое для первой установки и настройки или аналогичное. |
| * //[[docs:guide-user:|User Guide]]// most of the documentation for users goes here | * //[[docs:guide-user:|Руководство пользователя]]// большая часть документации для пользователей идет здесь |
| * //[[docs:guide-developer:|Developer Guide]]// developer documentation | * //[[docs:guide-developer:|Документация]]// для разработчиков |
| |
| * **Tags** are different. While the structure is exclusive, you can place an article only in one subcategory, tags are more flexible. More of them can be placed simultaneously in one article, and thus allow for a more flexible categorizing. To reproduce this with the structure we could write symbolic articles, which are placed in different subcategories and redirect to one article. But let's not do that. Tags will prove most useful, when you want to search for routers with certain features. | * **Теги** разные. Хотя структура является эксклюзивной, вы можете разместить статью только в одной подкатегории, тэги более гибкие. Многие из них могут быть размещены одновременно в одной статье и, таким образом, обеспечивают более гибкую категоризацию. Чтобы воспроизвести это со структурой, мы могли бы писать символические статьи, которые помещаются в разные подкатегории и перенаправляются на одну статью. Но давайте не будем этого делать. Теги будут наиболее полезны, если вы хотите искать маршрутизаторы с определенными функциями. |
| * [[meta:tags]] Overview | * [[meta:тег]] Обзор |
| |
| **Sidebar** | **Боковая панель** |
| To ease navigation, we use a sidebar, in two places to "animate" it, show more or less links depending on where you have clicked. Any change should be mirrored in both files (if relevant). | Чтобы упростить навигацию, мы используем боковую панель, в двух местах, чтобы «оживить» ее, показывать более или менее ссылки в зависимости от того, где вы нажали. Любые изменения должны отражаться в обоих файлах (если это необходимо). |
| * //[[docs:sidebar|Sidebar for Docs section]]// | * //[[docs:Боковая панель для раздела документы]]// |
| * //[[sidebar:|Sidebar for general section]]// | * //[[sidebar:|Боковая панель для общего раздела]]// |