Start Contributing

From unRAID
Jump to: navigation, search

Welcome to the world of Wiki editing! As an editor, you will be adding to the knowledge base, freely available to all. Your contribution may be fresh new content, or in making existing content more readable, or in fixing mistakes, all of which are equally welcome.

unRAID Wiki Editing Guidelines

Use the following as a guide to writing better wiki contributions. ( See more here. ) Although the guidelines below may inhibit your enthusiasm for contributing something to the Wiki, they are simply here to assist you, and to encourage some consistency and quality in the writing.

We actually want you to add incomplete and unfinished work, because after all, that is how every wiki page starts! All wiki pages are a work-in-progress. They often start with a very rough draft, gain additional content, get edited and corrected, and continue in a cycle of updates and edits.

  • Gear your wording towards a newbie unRAID user.
  • You can assume users are proficient computer operators;
    • i.e. what is a hard disk; what are USB, SATA, IDE; what is a motherboard; what is the Internet; etc
  • Do not assume any knowledge of Linux or Linux commands.
    • Tools like cron, hdparm, smartctl should be explained (or links to explanations added) if cited.
    • If not already obvious, it should be made clear that tools like ifconfig and ethtool are Linux commands.
  • Do not assume programming skills.
  • If you are writing an advanced article, you should identify the target audience and any "disclaimers" up front.
    • Advanced articles can make more ambitious assumptions about computer skills, but should still, in general, assume as little knowledge as is practical considering the subject matter.
  • Code (programming code snippets, scripts, and console commands) should be heavily commented.
  • Code and scripts should clearly highlight where and how to make user-specific changes.
  • If you cite an article or post, add a link to it. Don't make the user have to search for it.
  • Keep the style of headings consistent throughout a page, both in the levels of headings used, and the usage or non-usage of capitalization and punctuation.
  • Keep headings as short and simple as possible, with an absolute minimum of punctuation. This is because every heading becomes a usable link.
    • An example, "What if there's something really wrong, for example, maybe multiple drives are missing?" will become "What_if_there.27s_something_really_wrong.2C_for_example.2C_maybe_multiple_drives_are_missing.3F" in the link to it.
  • Because headings become the direct links to parts of the page, craft them carefully, considering how they will be used in the future. They should never contain information that could change.
    • An example, "Status as of 3/04/99" would not be a good heading, because when it is updated in the future, a different date would be wanted, but changing a heading breaks every link to it. If you had a forum post that used that link/heading, it would no longer work. Better to use the simple heading "Status", then follow it with a note about the date. Notes can be changed any time, headings should never be.
    • Another example, "Managing 16 array drives" would quickly become obsolete, as the maximum number of drives often increases. "Managing a full array of data drives" would be a better heading.
  • In general, the wiki is written for the latest production release of unRAID, unless otherwise noted. Sadly, it is only too common for sections to quickly go out-of-date. If you notice obsolete information, please consider updating it yourself, or at least point it out to others.
    • Where necessary, add an appropriate version note, such as the earliest version a feature was added, e.g. The cache drive feature (added in version 4.3 - Pro only).
    • If a topic, note, or comment only applies to a particular version or range of versions, it is very important to add a version note.
  • Always preview your work, no matter how minor the change. Please PLEASE click the Show preview button next to the Save page button, and double-check both the content you have added or changed, as well as the formatting of your content and how it fits with the rest of the page. It's amazing how easy it is for a small and almost inconsequential change to wreck the formatting style of a wiki article.
  • Always test every link that you may add or change.

How To Edit a Wiki Page

  • See the MediaWiki Help link on the left side of this page. It appears there on every Wiki page.
  • A great way to learn is to study the History of any page. At the top of each Wiki page is the history tab, which when clicked, shows the list of saves to that page. There are 2 columns of little clickable circles, for selecting versions to compare. If you click on the very bottom circle, then also click the circle above and to the right, then click the Compare selected versions button, you will see the actual changes made in that session. You will see both the new content that was added, corrections made, and the Wiki formatting codes used. If you then click the Next diff link (toward the upper right), you will be able to progress through all of the changes made, that brought this page to its current state.
  • Register first, and please use the same name you registered in the unRAID forum
  • Please make sure you are logged in whenever you edit Wiki pages, so your user name will be attached to your work
  • To open a page for editing
    • see MediaWiki help page for general page editing
    • click the edit tab at top
      • Or double click on an empty place on the page, if you have enabled this double click in your Wiki preferences
      • If there is no edit tab, then you are viewing a locked page, and cannot make changes. You can still view the underlying code, by clicking the view source tab.
    • After editing the page, ALWAYS preview your work, by clicking the Preview button at the bottom.
    • If you only corrected a few misspellings or typos, or other minor format changes, then check the This is a minor edit box
    • Please add a short but meaningful summary note, to the Summary: box at the bottom. It helps others locate a specific change.
    • While you can click the Save page button after each small change, it is better to make your edits and click the Preview button (to check how it looks), then continue repeating this edit-and-preview cycle until the batch of related edits are complete, and then only when you are satisfied with the entire editing job, Save the page with an appropriate Summary note. Each save creates a new stored version of the page, with a diff of each change visible on the Recent Changes page. Always disciplining yourself to add an appropriate Summary note will help you best determine when to Save a batch of related edits.
    • After previewing the page to ensure accuracy and that the formatting will display as intended, and after adding a short summary note, then click the Save page button, and your changed page now becomes the current page.
  • Adding a new page
    • On the page that will link to your new page, create a Wiki link, with the exact article title of your new page, as if it already existed!
      • For example, edit an existing page and add => "See [[My New Page]]"
    • When you save the page or preview it, you will see the new link, in red. A red Wiki link means there is a future page of that title, but it does not have any content yet.
    • Click the link and the new page with your title will open, ready to fill.
  • Adding bold and italics
    • see MediaWiki help page for bold and italics
    • For bold, enclose item with 3 apostrophes
      • '''bold text''' will display as => bold text
    • For italics, enclose item with 2 apostrophes
      • ''italicized text'' will display as => italicized text
    • For bold and italics, enclose item with 5 apostrophes
      • '''''bold and italicized text''''' will display as => bold and italicized text
  • Adding headings
    • see MediaWiki help page for headings
    • Headings become the links to internal parts of the page, so be very careful in how you craft them. Please see the unRAID Wiki Editing Guidelines above, to make sure your headings are useful, both now and in the future. To see what the link to a heading looks like, hover over the heading listed in the Table of Contents at the top.
    • ==Level 2 heading==
    • ===Level 3 heading===
    • ====Level 4 heading====
  • Adding bullets
    • see MediaWiki help page for bullets
    • begin the line with an asterisk, in the very first column
    • use more asterisks for bullets within bullets
      • (this line starts with 3, the line above starts with 2)
  • Adding numbered lists
    • see MediaWiki help page for numbered lists
    • begin each line that should be numbered with a pound symbol, in the very first column
    • use more pound symbols for numbered lists within numbered lists
  • Adding links
    • see MediaWiki help page for links
    • Both Wiki and external links may be shown as is or with replacement text
    • Wiki links do not need the full URL, just the article title, enclosed in a double pair of square brackets
    • [[Wiki Link]]
    • [[Wiki Link|Other Text]]
    • []
      • [] will display as [1]
    • [ Other Text]
    • Always preview and test every link you add or modify
  • Other tips
    • check the Recent Changes page often to monitor changes being made to the unRAID Wiki
    • practice on your own User page, click your user name on the very top line
    • practice on the Practice page. You can freely add or edit anything you like, and either cancel out without saving anything, or go ahead and save it. Every now and then, someone will clean it out. Just keep the language and content clean please.

Last Thoughts

We hope no one is inhibited from contributing to the unRAID Wiki in any way, by thinking they have to be careful to 'comply' with a set of standards. We do not want anyone to be afraid to add something, whether a full article, or just a helpful link, or even just a brief note pointing out a need (eg. 'Need note about XYZ'). We don't want someone to think it is too much work to write a fuller and more polished and fully compliant article, and walk away without contributing anything. We would like to see more participation, by more types of users. Creating a useful wiki is an ongoing process, that uses the differing skills of its participants in an evolutionary way. One points out a need, another adds a stub for it, someone else inserts a sentence or two, another adds a link, another adds a full writeup, several others correct the spelling and grammar, and someone may 'complete' it, by adding a version note and rewording parts of it for the newest of users. Later, others will update it as new information dictates. A wiki is not necessarily a collection of polished and professional articles (nice goal though), but is more like a garden, with plants in many stages of growth, from seeds to healthy trees.

This document should be short and explain and de-mystify contributing content for the most basic of user.