Remove the manual from website and port to wiki

[NAS]

Let me put it another way...

 

has anyone ever been on any forum that hasnt lost a wad of posts though a virus or compromise or other tom foolery. Im all for these links but we should work on the assumption that the forum will lose info (by default it probably drops ancient posts anyway or will do after an upgrade and the option changes - ive learned this from bad experience).

 

The act of converting forum post info to the wiki is what the wiki is all about. We should get in the habit of doing it and not the habit of posting a link in the wiki and forgetting about it. Sure its work but its the difference between writing a book and making notes about a book your going to write

[SSD]

I think you're getting annoyed.  Not my intent.  Many apologies. But ...

 

I just don't agree that this wiki is going to be a book as you describe.

 

Converting even the meager set of links I've posted is many hours of work. 

 

My idea of the wiki looks something like this ...

 

1.  Official Documentation

2.  Official FAQ (maybe)

3.  Beta Documentation - copy of official documentation but free to be updated by users, selectively incorporated into Official Documentation (after Tom's review and editing) at next official version release

4.  Troubleshooting Page

5.  User contributed FAQ(s) - general FAQ, How-Tos, hardware compatibility tables, benchmarks, and other special user-contributed wiki content

6.  Best of the Forums links

 

Your concern about the forums getting lost is a real fear.  I suggest putting this in Tom's court, though.  Maybe he needs the forum server to be on an unRAID array.  The forums are at least as important to him as they are to us.  A little prodding will get it on a backup schedule (if its not already) IMO.

 

A couple random thoughts ...

 

- If every posted link to a thread is going to be followed by a request to summarize it in the wiki, we are going to discourage not encourage participation

 

- I have seen many forums with "sticky" posts at the top with categorized links to threads.  It is how I usually learn about a new product.  I have not seen this level of detail duplicated in a wiki.

 

Sorry if I am being belligerent.  I'm curious as to how others are feeling about this.  RobJ, JoeL, WeeboTech, bubbaq, Billped, you, me (sorry for anyone I'm forgetting) are likely going to be the ones doing the heavy lifting here.  Is everyone on board?  Maybe I'm all wet ...

[NAS]

lol you could be more wrong... i am so not annoyed its as if i swallowed the little book of calm

 

I reckon we just go for it and let natural evolution work its magic.

 

 

Go for it man whatever you like we can always revert

[WeeboTech]

The delete key is only a pinky stretch away!!!! LOL  (just kidding)

[NAS]

I had a thought.

 

How about a whole new website for the GPL version components of unRAID. This gets rid of all the clarifying Official and Unofficial splits.

[NAS]

Heres a good one.

 

The unRAID manual doesnt actually tell you how to install unRAID

[RobJ]

The unRAID manual doesnt actually tell you how to install unRAID

 

The current installation page at http://lime-technology.com/wordpress/?page_id=46 has served very well for many of us, but does have 2 flaws.  The instructions work well in most cases, but it has no help if something goes wrong.  The primary installation problem that people have is preparing their USB flash drive to boot unRAID.  It would be good to have links to the Boot problems section of the Troubleshooting page, where there are tips about preparing the flash, such as using the HP tool, removing U3, and using the -ma option with syslinux.  In line with Brian's suggestion, perhaps a beta version of the installation page could be created in the wiki, with appropriate wiki links within.

 

The other problem with this installation page is that there is a link to the old Hardware Compatibility page, which is rather out-of-date, very limited, overly technical for many new users, and may very well have caused Tom to lose sales.  Many non-technical potential users may look at that page and decide their hardware may not be compatible, and go elsewhere.  That page should be removed from the Lime Technology web site, and replaced with links to the wiki Hardware Compatibility page.  (Some of the chipset info should be merged into the wiki version.)

 

Speaking of pages to be deprecated/replaced, the link to the Official FAQ could be removed at some point.  Then that will leave the Official Documentation page with only one link, to the unRAID Manual, and perhaps that link could be brought back to the top page?

 

I have thought it might be nice to have a 'Getting Started' page/section, that would be based on the current installation page.  It could be an Official document.  Or an Installation section could begin the unRAID manual.  Windows users in particular often look for a Getting Started page or booklet, or a Quick User Guide.

[RobJ]

Goofygrin's How-To Building an unRAID Server is already pretty close to being a Quick User Guide.  It just needs info about the HP formatting tool and removing the U3 partition, and a few additional wiki links, and a little updating.

[NAS]

I concerted (very roughly) the section from the www site to wiki format here:

 

http://lime-technology.com/wiki/index.php?title=USB_Flash_Drive_Preparation

 

I removed most of the BIOS stuff as it was half hearted and deserves a full section on its own.

 

Very quickly our unofficial documentation is surpassing the official stuff abeit our stuff need organised better i.e. the unofficial hop page should probably link to the relevant bits in order like chapters in a logical book. The appendixes of this book could be the How To stuff etc.

 

Im really impressed guys.

 

What do you think of my separate GPL url suggestion above. I dont think it takes away from Toms stuff at all and makes the split between our friendlyt help and his official help much clearer.

[WeeboTech]

One of the most common problems is still there.

 

c:\syslinux.exe f:

must be

c:\syslinux.exe -ma f:

 

Not having a MBR and an active partition are a big cause of boot failure.

[SSD]

(NASuser - please check your PM.  I had sent you a note Tuesday and awaiting reply.  Thanks!)

(RobJ - saw your updates to the Best of the Forum section - excellent work!  Hope everyone will spend just 10-15 minutes adding their fav links)

 

I have a few wiki suggestions ... more like standards ... that we should consider for wiki content.  I'm not trying to say these, as I've worded them, should be the standards, but rather generate some discussion about these types of topics and agree on some standards:

 

1 - By default, the content should be geared towards a newbie unRAID user and a proficient computer user.  Basic computer knowledge is assumed (what's a hard disk, what are USB, SATA, IDE?  What's a motherboard? what's the Internet etc.).  But knowledge of advanced concepts (e.g., programming), Linux commands / tools (e.g., cron, hdparm), diagnostic software (e.g., smartctl), messaging protocols (Usenet, torrents, IRC, etc), computer applications, should not be assumed.  If referenced in a particular article, at a minimum links should be provided where prerequisite information can be found.

 

2 - If you are writing an advanced article, where more than basic knowledge is needed to understand and benefit from the 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.

 

3 - Articles should be geared to the latest production release of unRAID, unless otherwise noted.  The version number(s) should be included, and updated as needed, as new versions come out.  One example would be to say the earliest version a feature was added (e.g., The cache drive feature (added in version 4.3 - Pro only) can be used as follows ...)

 

4 - Info about PRIOR versions or BETA versions should be added parenthetically if it is important to differentiate.  My feeling is that info on older versions should quickly be removed. as it tends to confuse the reader.  (Right now I would think that anything earlier than 4.2.1 should be removed or moved to a depricated section of the wiki).  Certainly users are not required to update their software, but it is a burden to try to address prior versions as new articles are written.  If they want help from the wiki, it is reasonable to assume they are on a relatively new version.  Everyone should have a thick skin about seeing info written months ago about a feature than has been substantially changed disappear.  (The history is always there for you to resurrect and update).

 

Thoughts?

[NAS]

OK i have made quite a number of changes based on bjp999 suggestions and a few things i wanted to do myself.

 

The homepage is better (but still not complete).

The community launch page follows a much more logical flow making the assumption it is for new users

I have added a highly paraphrased bjp999 documentation ruleset. (Note to bjp999: your ideas are brilliant but your far to wordy. User wont read more than a few lines

Various other little tweaks.

 

bjp999 theres a reason i didn't answer. I work on a few GPL projects and if i get a task or something to read that cant be dealt with within a couple of minutes it goes on a todo list. Any GPL todo immediately is lower priority than paid work. So the moral is if you want a quicker answer say less more often.

[SSD]

Ha! Ha!

 

This is just for fun!  But try not to wait a week next time.     (Even an "I'm swamped, give me a few days" is enough.)

 

Homepage looks better.  I like moving links to the top.  Still hate the "It may be less accurate and diverge from normal unRAID system usage." line.  Sounds like the "dark side".  Adds no value (disclaimer already there)  Whatever ....

 

The standards stuff was to discuss here.  Wasn't asking for you to add it to the wiki.  I do like what you did with it.  Just hope everyone agrees. 

 

Now that we have standards, I think your IRC artcile needs to be beefed up to follow them.    (You might also consider adding "suggested hours" and make them rather short.  Otherwise people may go there, find no one to talk to, and not come back.)

[RobJ]

I have a few wiki suggestions ... more like standards ... that we should consider for wiki content.  I'm not trying to say these, as I've worded them, should be the standards, but rather generate some discussion about these types of topics and agree on some standards:

 

1 - By default, the content should be geared towards a newbie unRAID user and a proficient computer user.  Basic computer knowledge is assumed (what's a hard disk, what are USB, SATA, IDE?  What's a motherboard? what's the Internet etc.).  But knowledge of advanced concepts (e.g., programming), Linux commands / tools (e.g., cron, hdparm), diagnostic software (e.g., smartctl), messaging protocols (Usenet, torrents, IRC, etc), computer applications, should not be assumed.  If referenced in a particular article, at a minimum links should be provided where prerequisite information can be found.

 

2 - If you are writing an advanced article, where more than basic knowledge is needed to understand and benefit from the 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.

 

3 - Articles should be geared to the latest production release of unRAID, unless otherwise noted.  The version number(s) should be included, and updated as needed, as new versions come out.  One example would be to say the earliest version a feature was added (e.g., The cache drive feature (added in version 4.3 - Pro only) can be used as follows ...)

 

4 - Info about PRIOR versions or BETA versions should be added parenthetically if it is important to differentiate.  My feeling is that info on older versions should quickly be removed. as it tends to confuse the reader.  (Right now I would think that anything earlier than 4.2.1 should be removed or moved to a depricated section of the wiki).  Certainly users are not required to update their software, but it is a burden to try to address prior versions as new articles are written.  If they want help from the wiki, it is reasonable to assume they are on a relatively new version.  Everyone should have a thick skin about seeing info written months ago about a feature than has been substantially changed disappear.  (The history is always there for you to resurrect and update).

 

I like these 'Guidelines to writing unRAID wiki articles', and what NASUser did with them (although I prefer the wordier version of them)!

 

But I have to qualify that by saying I hope no one is inhibited from contributing to the wiki in any way, by thinking they have to be careful to 'comply' with any standards.  I'm just afraid someone might be ready to add a helpful link, or even just a brief note pointing out a need (eg. 'Need note about XYZ'), and think it too much work to write a fuller and more polished and compliant article, and walk away without contributing anything.  I would like to see a lot more participation, by many types of users.  To me, 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 finally someone 'completes' it, by adding a version note and rewording parts of it for the newest users.  I see a wiki not as a collection of polished and professional articles (a nice goal though), but as a 'garden' of writings, in many stages of growth, from seeds to healthy trees.  (oops, excuse the flowery stuff)

 

As to removing 'anything earlier than 4.2.1', there are a number of users with Realtec driver problems (who can't use v4.1 and v4.2) and no desire to use a beta, who are therefore still using v4.0.  Although older info can be confusing, I would rather see it kept but clearly delineated and 'labeled', with a note as to the version or versions it applies to.

 

NASUser, I'm assuming you were going to add more to the Start Contributing page?  Right now, the Start Here link to the page implies that a user could find instructions on how to edit a wiki page, but when he arrives here, he only sees rules about what he writes, nothing about the mechanics of editing a wiki page.  It doesn't seem particularly friendly or helpful, but perhaps I'm ahead of the game, you just hadn't finished, or were waiting for someone else to write it...  Sorry, I'm probably premature.

[NAS]

I def will add more but I am on hiatus until Tom comes back. Were creating too much of a backlog for him to catch up on and things are going to be missed.

 

In the interim change anything you feel necessary be brave

[SSD]

I like these 'Guidelines to writing unRAID wiki articles', and what NASUser did with them (although I prefer the wordier version of them)!

 

But I have to qualify that by saying I hope no one is inhibited from contributing to the wiki in any way, by thinking they have to be careful to 'comply' with any standards.

 

To be honest, when I originally wrote those up I thought they would be more of a set of standards that WE, the primary authors of content there, would try to follow.  I thought we'd talk about what skills that we should assume and which ones we shound not assume, and refine what we thought was a reasonably good set of standards / guidelines for posting new content.  The genesis was reading through some sections I thought the amount of prerequisite knowledge to understand and apply what was writen was too high.  For example, I don't use IRC and felt that the IRC page was very spartan and would be hard to follow for someone unfamiliar with tools that used that protocol.

 

On the new content front, it took me a while to figure out that to create a new wiki page I first had to create a reference to the page from another page.  Seemed a bit bass-ackward, but once I figured it out it worked fine.  Users trying to contribute new content to an existing page should have an easy time of it, but creating new pages is tougher.

[NAS]

... For example, I don't use IRC and felt that the IRC page was very spartan and would be hard to follow for someone unfamiliar with tools that used that protocol...

 

The reason that page is so short is that I am not prepared to spend any more time on it.

 

There has been a sum total of 3 lines typed on the IRC by one member since i opened the channel. Ive already done alot of work for what is a completely ununused resource. Now i know people are going to say "the reason why that is happening is because the docs don't explain how to join" but I pre-empt this by saying... 1. most uber members here know how to use IRC and 2. no ones posting asking quesitons how to join as they attempt to do so.

 

Essentially there is no interest in IRC. In a few weeks i will close down the channel.

[SSD]

NASUser, you've done a tremendous job leading the charge on the wiki update.  Please don't take the following as critical.

 

On this IRC issue, I immediately asked a bunch of questions (which others answered) about IRC - and suggested that you establish some very limited hours to attempt to generate some interest, which never happened.  I also suggested, at least twice, enhancing the IRC page to make it easier for non-uber forum members (like me) to get in easily and painlessly.  I thought that would take only a couple minutes for someone familar with the IRC, but since I know almost nothing may not have realized the effort I was suggesting.

 

Bottom line:  It would take leadership and determination to get participation on the IRC.  If you don't have the time or interest, I think closing it down is the right choice, rather than getting you frustrated about the effort and/or expense of maintaining an unused resource.

[NAS]

Your missing the point IRC is not a formal place. It neither takes "leadership" or "determination" to get a bunch of people chatting all it takes is people wanting to chat.

 

As for joining a channel a few minutes on google is all it would take to work it out but if you still think there is a need post in the IRC any questions you have an I will endeavour to talk you through it but its no more complicated than:

 

Download IRC client, add server name and channel, press connect.

 

The only way to make it even more trivial to join; is to setup an JAVA chat client but that would need Tom or someone to volunteer some webpage (which i requested with no answer).

 

Im not annoyed I just dont want to spend any more time on it until it is actually used. Time is money and unRAID suffers from to many brilliant ideas and keen hackers but no follow up so everything stallsl.

 

I am sure  the time will come when this will all change but that time is not here yet.

[NAS]

Big thanks to RobJ for all the work on the releases page !

 

I have started adding MD5 sums to this same page but i have access to very few older versions.

 

Does anyone have any more versions we can make md5s from for completeness?