Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
playground:gandalf [2024/07/25 15:05] – johnszplayground:gandalf [2024/07/25 18:45] (current) – johnsz
Line 1: Line 1:
 ==== John's playground space ==== ==== John's playground space ====
 +
 +[[docuwiki|]]
  
 ====== Wiki contribution guide ====== ====== Wiki contribution guide ======
  
-The following standards should help keeping the wiki consistent, easy to understand for newbies, and easy to edit for casual contributors.+The following standards should help keeping the wiki consistent, easy to understand for newbies, and easy to edit for casual contributors. There can be exceptions in some cases where it makes sense, but there should be a good reason for that.
  
-There can be exceptions in some cases where it makes sense, but there should be a good reason for that. 
- 
-\\ 
 {{section>meta:infobox:registration_disabled&noheader&nofooter&noeditbutton}} {{section>meta:infobox:registration_disabled&noheader&nofooter&noeditbutton}}
  
Line 15: Line 14:
 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 on a device]]. 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 on a device]].
  
-- **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!\\+- **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!\\ 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.\\+- **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.\\+- **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!\\ - **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!\\
Line 35: Line 34:
 - **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 on a device]] or this [[:docs:guide-developer:helloworld:start|"Hello, world!" for OpenWrt]]\\ - **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 on a device]] or this [[:docs:guide-developer:helloworld:start|"Hello, world!" for OpenWrt]]\\
 \\ \\
-- **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 =====
-===== Structure ======+
  
 To give the Wiki a better structure, we employ ''namespaces'' and ''categories'' (and ''tags''): To give the Wiki a better structure, we employ ''namespaces'' and ''categories'' (and ''tags''):