Table of Contents

FIXME This page is not fully translated, yet. Please help completing the translation.
(remove this paragraph once the translation is finished)

Guia de contribuição do Wiki

Os seguintes padrões devem ajudar a manter o wiki consistente, fácil de entender para novatos e fácil de editar para colaboradores casuais.

Pode haver exceções em alguns casos em que faça sentido, mas deve haver uma boa razão para isso.

Mantras

  1. Os artigos devem ser fáceis de ler e fáceis de editar, mais simples é melhor. Os artigos devem ser formatados usando apenas os recursos básicos encontrados na GUI do editor, além da codificação e da construção da tabela, onde necessário.
    Por que? A formatação mais avançada daria a este wiki uma aparência mais “profissional”, mas também seria mais difícil de ler e editar para usuários e colaboradores casuais. Layouts mais avançados com guias e botões são mais compactos, mas geralmente são mais confusos do que um layout mais simples com apenas uma única lista de ações e links em que os leitores rolam e clicam. Além disso, um layout simples não interativo permite uma impressão fácil. Por exemplo, veja este tutorial Instalação de fábrica: instalação pela primeira vez em um dispositivo.

  2. Evite duplicar informações dentro da wiki : Informação sobre um mesmo tópico deve aparecer na wiki apenas uma vez. Se ela é requisitada em outro lugar, devemos nos referir a ela usando links!
    Por exemplo, se você está escrevendo um tutorial e um dos passos é “configurar armazenamento USB” você deve disponibilizar um link para Usando dispositivos de armazenamento. Você NÃO DEVE escrever (ou copiar e colar) o mesmo procedimento no novo tutorial!

  3. 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 ipv4. Some example upstream wikis: i.e. Linux WiFi drivers 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.

  4. 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.

  5. 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.

  6. 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: Using the Image Generator (Image Builder)

  7. 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: USB 3.0 and WiFi problems

  8. 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).

  9. 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.

  10. 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 Factory install: First-time installation on a device or this "Hello, world!" for OpenWrt

  11. 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):

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).