Remove the manual from website and port to wiki

[NAS]

write a nice "please update" and don't spend hours writing obsolete documentation

 

I'm not suggesting toi re-write old documentation. Make what ever exists, available via hyperlink once it has been created fine.

 

If someone can get me the older versions of the officially released stuff i will intigrate it into the wiki and make sure it all flows nicely.

 

From now on I propose we use wiki change control. If we can agree to do this (and more importantly peer review the changes) I can make the official documentation open for all registered wiki users to edit. Then I can use the lauch page to link to the version it has now and a seperate set of links to the work in progress.

 

How does that suit?

[WeeboTech]

Sounds good.. One thing that puzzled me a bit..

On the main limetech page, there is a link to Manual and Troubleshooting...

http://lime-technology.com/?page_id=47

 

So are we duplicating something here? Will those links eventually point to Wiki documentation link?

 

 

[NAS]

Sounds good.. One thing that puzzled me a bit..

On the main limetech page, there is a link to Manual and Troubleshooting...

http://lime-technology.com/?page_id=47

 

So are we duplicating something here? Will those links eventually point to Wiki documentation link?

 

 

 

Spot on. This whole thing started form my original post that the www site and the wiki have dupe info. Hopefully in the next few days the stuff you linked to there will disapear and the link to the "wiki" will be changed to "Documentation" since most people have no clue what a wiki is.

[Joe L.]

Sounds good.. One thing that puzzled me a bit..

On the main limetech page, there is a link to Manual and Troubleshooting...

http://lime-technology.com/?page_id=47

 

So are we duplicating something here? Will those links eventually point to Wiki documentation link?

 

 

Actually, that link is to some of the old documentation that appled to older releases of unRAID.  As an example, an excerpt:

[pre]

Add one or more new disks

 

This is the normal case of expanding the capacity of the system by adding one or more new hard drives:

 

  1. Stop the array.

  2. Power down the server.

  3. Install your new hard drive(s).

  4. Power up the unit.

  5. Start the array.

 

When you Start the array, the system will first format the new disk(s).

When this operation finishes, all the data disks, including the new one(s), will be exported and be available for use.

[/pre]

Notice, it said nothing about the Devices page on the web-interface, or that you would need to stop the array, assign the new devices, then re-start the array before you would see them.  It  said nothing about the checkbox to confirm formatting... 

 

Is it no wonder we get users who are confused when they try adding a disk to the current version of unRAID.  They don't see the drive they just added, even though they followed the instructions in the "official documentation" , and often ask why it does not work like the documentation says it should.  Obviously, that page in the "official documentation" was written at a time when device management was not as flexible as it was today, and it needs updating.

 

Joe L.

[WeeboTech]

What I like about the manual in on the main site is it has the whole table of contents expanded/indexed in section numbers.

 

In the Wiki I only see index/pointers to the main sections.

 

Personally I like/prefer the Initial expanded table of contents as it reads more like a book/manual.

 

I can easily scan and go right to the topic I really need.

With the current Wiki implementation I have to jump to each interface section's subordinate page to find the topic I need.

 

I think all we really need is a Table Of Contents / Indexing block that looks lie the top of each interface page, yet links all the subordinate pages somehow.  Maybe that's not possible in this Wiki.

 

 

 

 

 

 

[WeeboTech]

was written at a time when device management was not as flexible as it was today, and it needs updating.

I suppose that's why the Documentation is being moved to the Wiki, to bring it in line with the current production release.

[NAS]

What I like about the manual in on the main site is it has the whole table of contents expanded/indexed in section numbers.

 

In the Wiki I only see index/pointers to the main sections. ...

 

The wiki is pretty flexible to a point. If i could understand better what you like I can look into it.

 

One thing I dont want to do is split it into more pages than it already is. The ONLY reason I split it up into the main sections is that some browsers fail dramatically when editing extra long wiki pages which causes all sorts of grief with version control.

 

In the interim if anyone finds any mistakes they want fixed in the wiki use the sandpit page and post here an i will fix. Until i get the versioning done i don't want to unlock it.. especially in a time of such radical opinions on what it should look like etc.

[NAS]

Two updates to the official branch. These are ratified with Tom:

 

1. The manual will be a single page to ease printing and version control.

2. The documents in the official branch will be locked and not editable.

 

So if you spot a mistake the best way to do this is to document the fixes in a temp wiki page and post so Tom or I can fix it.

 

[NAS]

Image upload to the wiki is now fixed but locked to sysop level to stop abuse in the interim.

 

So if you want to add anyimages stick em on something like imageshack and link to them from there or let me know and i will upload them for you

[WeeboTech]

I like how it has a full Table of contents with links to every topic.

 

Now what we need is a link on the forum header to the Wiki.

I found it helpful when perusing the ReadyNAS foruims.

 

Also, I think there should be a screen capture per Main menu selection.

 

Screen capture of MAIN, USERS, SHARES, SETTINGS, DEVICES.

A picture is worth a thousand words!

[Joe L.]

The "official" manual should include a description of the differences between the three versions of unRAID and describe how to upgrade from one to the next.

Nowhere are the words "Plus" or "Pro" mentioned, and when describing user-security, it is not mentioned that User-Security is not available on the free "Basic" version of unraid.

 

The cache drive feature is not mentioned at all... It probably also needs to be added to the official documentation.  Recently, I think Tom mentioned in a post that he would be changing the meaning of "Split level 0" Not certain if the official manual describes the current functionality, or the new.

 

These additions will eliminate a user saying "Why can't I set user-security?"  or "How do I upgrade from Basic to ...?"

[SSD]

I am going to mention this one more time, because I think it is a good idea and would improve documentation quality.

 

Make a copy of the offical documentation and call it "beta".  Allow users (or select users) to contribute to the beta documentation.  When a new version goes final, Tom can do a detailed review of the "beta" documentation, rewrite or remove sections that he's isn't happy with, add stuff only he knows, and promote the beta documentation to "final" status.  In this way, problems in the existing documentation can be fixed / enhanced  (e.g., screen shots), documentation for new features can be added, and it removes a huge burden from Tom when it comes time to update the documentation for a final release.

[NAS]

If people would actually work on the document its a good idea and theres nothing stopping anyone just doing this.

 

Keep in mind though that Tom is working on 4.3 documentation this now so it would probably be best to wait until that is out to save duplication of effort.

[SSD]

If people would actually work on the document its a good idea and theres nothing stopping anyone just doing this.

 

I do think there is something stopping people - access.  People are not able to modify the official documentation (except you, I think).  I do not think that user's should be able to directly update the official documentation anyway.  But I DO think that the JoeL's, RobJ's, Billped's, WeeboTech's and many others of us would add screenshots and more detailed information to the documentation if there were a way to do that via a beta copy.  Tom would review and approve (or slash and reject) the changes as part of each "final release".

 

Keep in mind though that Tom is working on 4.3 documentation this now so it would probably be best to wait until that is out to save duplication of effort.

 

Agreed.  But imagine how much easier this might have been for him if users had already written up sections on the new features, and all Tom had to do was edit and wordsmith!

[RobJ]

I'm happy to see you have moved the FAQ to its own page, but I believe it should be moved to the user-written sections.  If you look at the current FAQ, at first glance, you see 7 usable questions and answers, and think OK, this is good.  Then you think about it, and you can quickly think of dozens more questions that should be there, and the more you think about it, the more you can come up with.  I would not be surprised to see a hundred or more, if people really get involved with adding Q's to it.  There needs to be a lengthy section just about User Shares, and the Cache drive should have a small section.  User Security needs a section, as do so many more topics.  Wouldn't it be great to have a generalized hardware section, on things like 'What is the difference between PCI, PCI Express, and PCI-X', energy conservation tips, power supplies, disk controllers, port multipliers, understanding bandwidth considerations, network questions, 'What is DHCP', performance considerations, etc etc.  There are numerous FAQ topics that are not specific to unRAID, but are important to unRAID users.  unRAID-specific questions are of course of first importance.

 

I also note that two of the seven answers within the current FAQ include phrases like 'reset the array configuration data', which I venture to say, many even of the knowledgeable forum readers would have a hard time knowing exactly what that means, or how to go about it.  And worse, it is not explained even in the Manual.  There is a hint about it, at the end of a section about multiple missing disks, a paragraph few may read.

 

Until Tom has a full time technical writer, this seems like a perfect thing for the users to flesh out, and Tom to occasionally review.  Turn it loose, let the users have at it.  Would you rather have Tom writing code or writing docs?

 

[RobJ]

I would also like to say I strongly agree with both of Brian's posts and thoughts.  I suppose I would go even farther, and say turn it all loose, unlock it all, and let registered users have the freedom to edit at will.  Certainly there will be the occasional abuse, but that just demonstrates both the beauty and the weakness of any Wiki.

 

[WeeboTech]

At the very least, the FAQ should be community editable since the community asks and answers many of the questions

[NAS]

Sorry gents for the for seeable the official documentation has to stay locked since its the Limetech LLC part of the wiki.

 

Just create a copy of the official documents in the unofficial section and expand them there. Same goes for the FAQ.

[SSD]

Is Tom on board with this concept? 

 

If so, I think there should be a separate wiki section identified as the "beta documentation" section.

[NAS]

Is Tom on board with this concept? 

 

If so, I think there should be a separate wiki section identified as the "beta documentation" section.

 

I see no reason why he wouldn't be that's the whole idea of a public wiki.

 

We don't need a beta section that's the whole point of the unofficial documentation section.

[RobJ]

I did a little tidying of the Troubleshooting page, and added a link to a new FAQ:  http://lime-technology.com/wiki/index.php?title=FAQ.  It's basically a copy of the the Official FAQ plus a little organization, some sections to put questions in, just to get things started.  Feel free to reorganize at will.

 

So have at it...

 

I did not create a copy of the current manual, as I think it was mentioned that Tom is working on it.

[RobJ]

NASUser, I put together an alternative Start page for the Wiki, for you to examine.  You don't have to use it, or any part of it, but I was hoping to spark some ideas.  I didn't really like the extra 2 pages you have to go to, before you can click on actual information pages (the Official Documentation page and the Unofficial Documentation page), and they had very little on them and were quite plain.  Also, it helped me learn more about Wiki formatting, so I was playing around.

 

I didn't know where to create the alternative Top page, so I used my User page:  http://lime-technology.com/wiki/index.php?title=User:RobJ

[WeeboTech]

I like it, Only thing is the color scheme should be consistent with the main page. i.e. look at the menus on the left.

[NAS]

Nice, nice indeed.

 

I would agree the colour scheme needs tweaked. Also I wouldnt be putting the "# Troubleshooting # FAQ # Hardware Compatibility" bits on the homepage for 2 reasons. First is i think less is more on a homepage and second the reason i put it on a seperate page was so other people can edit it. if we put it on the homepage only a couple of users can change it which is limiting.

 

Great look though

[RobJ]

Thanks.  The colors were among a number of things I 'copied' from the MediaWiki help pages and examples, never even thought about coordinating them.  I have to admit I'm not very good at that sort of thing, so will happily defer to others with more visual creativity and spatial sense.  The layout doesn't look that good to me.

 

I would like to see more about Lime Technology at the top, at least a big logo and blurb, and a system picture or 2.  The blurb should mention both the unRAID software, and that hardware systems are available from Tom.  Anything we can do to help Tom, helps us.

 

'Less is more' is a good principle, and I agree with it, but sometimes too much less can be a nuisance, causing extra clicking and confusion over where stuff is.  I like the idea of one-stop shopping, where everything important is immediately accessible.  There's probably a happy medium here somewhere.  I suspect you are more of the Apple Mac camp, that likes the extremely simple and clean marketing approach, a plain white box look, whereas I just see a lot of wasted space, and a complete lack of all the info I want to read.  I don't like clutter, but I hate having to go look for what seems like should have been right there at the beginning.  I suspect there are many users like you, and many like me.

 

And once you've settled on what links are important enough to go here, the page shouldn't change much at all, if ever.  All of the editing will be on the detail pages.

 

  (  And I still don't like all the Officials!    )