Feedback on "Upgrading to UnRAID v6" wiki page


RobJ

Recommended Posts

I really don't know where to put this, so for now it's here, in the Forum Feedback board, seems sort of related.  I needed a thread for anyone to place corrections and suggestions for the new guide to upgrading from v5 to v6.

 

  Upgrading to UnRAID v6

 

It's ready for beta'ing, before the masses upgrade to v6.0 Final.  It's understood that v6 is still in beta, and is still changing, so this guide will have to change too.  It's weak in some areas for sure, but here are a few areas I'd like immediate feedback.

 

* Minimum RAM for running v6 - certainly that depends mostly on how much you add/install to your unRAID system, but we need a minimum for those running lean, just a simple NAS.  In the past, we have generally recommended 1GB as a good minimum, but some have run with only 512MB.  Tom or Jon has posted a minimum of 2GB in their Hardware Recommendations, but I'm a little concerned that many unRAID users who haven't upgraded yet and have 1GB will be dissuaded from upgrading.  It does not seem to me to be a good reason not to upgrade.  Certainly, we want to provide them with reasons why adding more will be good for them.  I'd really like to hear from any users that have upgraded to v6 and still have only 1GB, what limitations and issues have you seen, if any?

 

* I thought I saw somewhere in someone's picture of v6 settings a way to change from eth0 to eth1.  It's not in mine, so did I dream it?  Or does it only appear if you have multiple NIC's?

 

* I don't have User Shares turned on, so that's probably why I couldn't find any Mover settings.  Where are they and what are they?

 

* We used to advise users about certain performance improvements, one of them being the  'blockdev --setra 2048' loop.  Is that still useful at all in v6?  Are there any performance tips, tunables tweaks that might be recommended to new upgraders?

 

* It's especially weak in the Dockers sections, and in the VM's sections.  I'm hoping users with appropriate experience in either will help out, add whatever they think should be there.

 

* Would like advice as to how to notify users of this guide.  I think I may have 'spammed' enough places, mentioning this guide, but I am thinking of adding a link to it in a post in each release announcement, if that seems right to others?  If not, any advice?

 

I'm sure there are holes and inaccuracies in the guide.  I appreciate any help to fix them.

 

I decided to add credits at the bottom to all those who have helped or whose words I've used.  Frank1940's help was especially great.

Link to comment

Haven't read the whole thing yet.

 

If you enable user shares, there is a Mover Settings tab (or probably section if untabbed) on the Global Share Settings page. This will allow you to set the mover schedule and manually invoke the mover. The default schedule is daily at 3:40 AM just as it has always been.

 

It is possible to edit syslinux.cfg directly in the webGUI. From Main - Boot Device, click on Flash. The Flash Device Settings page has a tab (or section) for Syslinux Configuration and you can edit syslinux.cfg there. If you don't do it that way, then you should probably use an editor that correctly handles linux line endings. I know the go file is actually passed through fromdos but not sure what would happen if you put DOS line endings in syslinux.

Link to comment

Perhaps a brief blurb on what a docker actually is, in the docker section.

 

Thanks, I'm sure you are right, but I feel I don't have sufficient experience to write one.  As you can see in the Learning about Dockers section, I cheated!  I just pointed to what others had written, which seems well written but doesn't completely answer the question.  The LimeTech Docker Guide gives a brief intro to them, then shows you how to create them.  Jon's User V6 Manual says why they are better, and describes many characteristics of them, but I still don't have a good clear and simple description.  After a fair amount of reading, my sense is that a Docker Container is a pluggable layered sandbox, pre-configured, prefilled with sand and toys.  Is that anywhere close?  I have yet to see the word 'sandbox' used anywhere, in connection with Dockers.  It's more than a layer, it's more than a sandbox, it's more than a combination plugin.  It sounds a lot like a VM!  But I know it isn't.  But then again, I haven't used them yet, which is why I would prefer to hear from a Docker user.

 

How would you define a Docker?

Link to comment

If you enable user shares, there is a Mover Settings tab (or probably section if untabbed) on the Global Share Settings page. This will allow you to set the mover schedule and manually invoke the mover. The default schedule is daily at 3:40 AM just as it has always been.

Thanks, as soon as I have time, I'll turn User Shares on and go there, and document it in the guide.

 

It is possible to edit syslinux.cfg directly in the webGUI. From Main - Boot Device, click on Flash. The Flash Device Settings page has a tab (or section) for Syslinux Configuration and you can edit syslinux.cfg there. If you don't do it that way, then you should probably use an editor that correctly handles linux line endings. I know the go file is actually passed through fromdos but not sure what would happen if you put DOS line endings in syslinux.

I did NOT know that!  Great feature, thanks for letting me know, I'll add it to the guide.

Link to comment

Perhaps a brief blurb on what a docker actually is, in the docker section.

 

Thanks, I'm sure you are right, but I feel I don't have sufficient experience to write one.  As you can see in the Learning about Dockers section, I cheated!  I just pointed to what others had written, which seems well written but doesn't completely answer the question.  The LimeTech Docker Guide gives a brief intro to them, then shows you how to create them.  Jon's User V6 Manual says why they are better, and describes many characteristics of them, but I still don't have a good clear and simple description.  After a fair amount of reading, my sense is that a Docker Container is a pluggable layered sandbox, pre-configured, prefilled with sand and toys.  Is that anywhere close?  I have yet to see the word 'sandbox' used anywhere, in connection with Dockers.  It's more than a layer, it's more than a sandbox, it's more than a combination plugin.  It sounds a lot like a VM!  But I know it isn't.  But then again, I haven't used them yet, which is why I would prefer to hear from a Docker user.

 

How would you define a Docker?

 

I'd be the last person you'd want to write anything like that, lol. i use terms like thingimy and watchacallit a lot.

I would say less on the tech aspect, something along the lines of an app in a box but with more tech aspect than that, lol.

 

good luck.

Link to comment

If you enable user shares, there is a Mover Settings tab (or probably section if untabbed) on the Global Share Settings page. This will allow you to set the mover schedule and manually invoke the mover. The default schedule is daily at 3:40 AM just as it has always been.

 

It is possible to edit syslinux.cfg directly in the webGUI. From Main - Boot Device, click on Flash. The Flash Device Settings page has a tab (or section) for Syslinux Configuration and you can edit syslinux.cfg there.

 

Done and done.  And thank you.  Feel free to suggest more improvements!

Link to comment

I've got 3 network interfaces in my Unraid machine and not found a way to select a specific eth interface.

 

It's one area that unraid is still a little weak on.

 

Thanks, I was hoping I hadn't dreamed it.  Sure thought I saw it on someone's Network Settings page.  Seemed like such a good idea, simple to select, and an easy way to deal with a nuisance issue.

Link to comment

If you enable user shares, there is a Mover Settings tab (or probably section if untabbed) on the Global Share Settings page. This will allow you to set the mover schedule and manually invoke the mover. The default schedule is daily at 3:40 AM just as it has always been.

 

It is possible to edit syslinux.cfg directly in the webGUI. From Main - Boot Device, click on Flash. The Flash Device Settings page has a tab (or section) for Syslinux Configuration and you can edit syslinux.cfg there.

 

Done and done.  And thank you.  Feel free to suggest more improvements!

b15 has moved the Mover Settings to Scheduler
Link to comment
  • 4 weeks later...

I really don't know where to put this, so for now it's here, in the Forum Feedback board, seems sort of related.  I needed a thread for anyone to place corrections and suggestions for the new guide to upgrading from v5 to v6.

 

I want to pass along my thanks for your guide.  I upgraded my 1 year old unRAID 5.0.5 NAS (which is a VM in a VMWare ESXi 5.5 server with a passed-through disk controller).  The process went very smoothly.  I did not have to modify the PLOP settings at all -- I just followed your guide to re-format the USB boot drive and update with software and configs as you indicated.

 

One question/comment.  In following the guide to copy over the files from the version 5 config directory, I note that it copies my older cache-dirs file.  Should that copy be excluded from the copy, or deleted afterwards?  It appears it is not active, but it might cause confusion.

 

I run a very bare-bones system, with no plugins.  I was configured with 1 GB of RAM, but since I had been reading in other places to go with 2 GB RAM, I did that.  Of course, in a VM environment, the RAM allocated is somewhat smoke and mirrors, as you can over allocate.

 

John

Link to comment

One question/comment.  In following the guide to copy over the files from the version 5 config directory, I note that it copies my older cache-dirs file.  Should that copy be excluded from the copy, or deleted afterwards?  It appears it is not active, but it might cause confusion.

You can delete it, as it's just ignored, superceded by the CacheDirs plugin.  I have to say it's the first instance I'm aware of, but if one user has it there, then there may be an instruction somewhere suggesting putting it there, so there may be others with it there too.  I'll add a note about removing it.

 

I run a very bare-bones system, with no plugins.  I was configured with 1 GB of RAM, but since I had been reading in other places to go with 2 GB RAM, I did that.  Of course, in a VM environment, the RAM allocated is somewhat smoke and mirrors, as you can over allocate.

From the little anecdotal evidence available so far, it seems like 1GB may be fine, but certainly 2GB would be 'finer'.  Either way you go, let us know how well or poorly it works for you.

 

Thanks for your feedback!

Link to comment
  • 1 month later...

Howdy itimpi,

 

I saw your terrific work, great additions to the wiki!  And I'm especially happy it's not just me to 'blame' now, it's more truly a community effort!

 

I'm sure you saw my tweaks of your work earlier, and I wondered if they were acceptable or just annoying.  I know I'm not as creative as others, not as good a writer, but do like making good things better.  That unfortunately is almost by definition annoying to others, and has often gotten me into trouble.  I'm a perfectionist, and they are by nature hard to live with, but I have long tried hard not to be.  So if you don't care for any change I make, feel free to change it back!

 

I tend to prefer less words whenever possible.  I've long noticed that whatever I start writing soon gets very long!  Plus, and this may only be me, if it doesn't get to the point quickly, my mind is far away.  The fewer the words the better for me, but that may not be best for others.  I will probably try to reword things as succinctly as possible, then others can expand it if they feel it necessary.

 

Almost all of your changes, I fully agreed with, often wished I had thought of it!  I did notice a few things, so just for discussion -

 

* Nice additions at the top.  I'm still planning to expand the opening to cover alternate methods depending on which version they came from.  But I got sidetracked, multiple times, thought I would have had it done by now.

 

* You added the 3 words "most users can" (into sentence beginning with "Once the backup is complete").  It feels like it's opening the door to more users using the No-format section, and we REALLY REALLY want users to format and start fresh.  I don't want to remove that section, because there will always be experienced users that want it (and you know who you are!), but we don't want anyone else using it.  However I am hoping to add more specific info to it, about the specific files to be copied over or deleted, but it's still dangerous for the less experienced to use.

 

* You moved the make_bootable stuff into the middle of the Copy Files section, and reorganized it all, added some good info.  For me, it seemed to make more sense in the Final Prep section, but I don't yet know your reasoning.  (Now there's nothing left to prep in Final Prep.)  The headers don't seem right, so I'm thinking of changing them to -

  Copy unRAID files

  Make it bootable

  Install license key

  Copy saved configuration files

  Done!

You may have better ideas.

 

* Concerning multiple .key files, I had put that you should only put the correct one in the config folder.  You have added that they could all be put in the config folder, and unRAID would find and match the correct one.  If you are correct, then my statement should be removed.  I'm not sure it's best to keep the keys all there, on all your flash drives, but I haven't thought this out yet (first I had heard of it).

 

* In 'Meet the new GUI', you commented how different it looks compared with v5, and I had noted how similar it looked, probably because I had been using v5 Dynamix (but many others used it too).  But even the stock one seemed similar to me, same content and general layout.  Perhaps we should drop any comment on how different or similar it looks, as either way it may not agree with a given users' perspective.  It's good you did it, because it gives me another perspective, that would not have occurred to me.  For me, content is king, the graphical stuff tends to be almost inconsequential in comparison.  You see products with 'major' improvements and a hefty upgrade fee, but all they have done is move a few things around, add prettier buttons, change colors and fonts, ...  I don't see a single change in their product, but they are trumpeting major improvements (probably to justify a ridiculous upgrade fee).  But I've digressed, far away...  *Our* new GUI is enormously enhanced, a worthy upgrade!  And free!

 

* In the next sentence, you changed commas to semi-colons.  Grammatically, I think they should be commas?  (I don't feel comfortable reversing someone else's work without asking!)

 

* About the Done button, we really should press for a behavior change.  I can't see how it can be justified to leave a page without saving changes, and it constantly causes confusion, seems non-standard.  Using 'OK' and 'Cancel' might seem like copying Windows, but would make it intuitive to more users.  It's good you expanded on how it works now.  We might even want to make it stronger, with a leading 'Warning!' in red.

 

* You added a line ("Plugins are ideally..."), but many plugins are not from LimeTech, so perhaps we should drop the "provided by Limetech".

 

* Limiting 'Research & Decision making' to virtualization - doesn't seem right to me.  Plugins are still the most common addon, and probably will be for a long time.  The decisions to make are all about what should be a plugin, what should be a container, and what should be a VM.  And plugins are how we add functionality to the NAS part, the basic unRAID server part.  The NAS wants attention too!  And there are very nice plugins to add, such as Community Applications, Server Layout, Unassigned Devices, etc, all improving constantly.  We're not totally deprecating plugins, we're trying to educate users about their changed role in the new architecture.

 

* In CacheDirs, you changed "**:" to "***", making the notes equal, but they aren't.  There are only 2 notes, each with 2 or 3 paragraphs.  I think I'll rework that whole section a bit.

 

* You added Docker recommendations within some of the plugin carry-overs, from PhAzE and overbyrn.  Maybe it's just me, but with all the strong recommendations we made earlier, about Dockers over plugins, it almost seems disrespectful to add it again here.  They have worked hard on them, done great work, fully converted them to v6, *and* there are users who still prefer the plugins, which is their right.  My feeling is that I'm not here to tell people what to do, but to provide the best info and recommendations I can, so they can make the best decisions.  Then I should stand back and fully respect their choices.  I do understand why you added them though, could probably have added more about the risks.  But it seems too much to me, possibly becoming irritating, and it's all been said and repeated above.

 

I hope you don't feel I'm being critical, I'm not, these were just items to discuss.  There were so many other changes you made (not mentioned above) that were very nice additions!

Link to comment

Perhaps, a suggestion that most users would be advise to use plugins only that are are necessary to the operation and/or maintenance of the basic unRAID OS.  That Docker Containers and VM's should be used to provide those services which are ancillary to the basic NAS function.  The reason being that the Ancillary services require dependencies that can be conflicting with each other as well as with the base OS.  In Docker Containers, everything needed by that container is self-contained and isolated within that container from everything else on the hardware.  The same claim can be made for VM's.  Updates to one component, whether it is a Docker Container, a VM or unRAID itself, won't break anything else. 

Link to comment

Howdy itimpi,

 

I saw your terrific work, great additions to the wiki!  And I'm especially happy it's not just me to 'blame' now, it's more truly a community effort!

I started off intending to make minor changes and got a bit carried away I am afraid.  I was not trying to remove anything but expand on some sections which seemed brief and add additional material in some areas.  In particular I was trying to look at it from the perspective of a naïve user who has little familiarity with the insides of unRAID without removing information that is of use to the more experienced user.  That does not mean that I did not miss some of the intent of the original wording.

 

I'm sure you saw my tweaks of your work earlier, and I wondered if they were acceptable or just annoying.  I know I'm not as creative as others, not as good a writer, but do like making good things better.  That unfortunately is almost by definition annoying to others, and has often gotten me into trouble.  I'm a perfectionist, and they are by nature hard to live with, but I have long tried hard not to be.  So if you don't care for any change I make, feel free to change it back!

I suspect that when one person tweaks it and the next one tweaks it again then the result is almost always better than the original.

 

One thing I know I did in a number of places was remove bullet points where I felt that the text did not need them as you seem to have bullet pointed nearly every paragraph.  To me that makes it easier to read, and also makes the bullet points more prominent.

 

I tend to prefer less words whenever possible.  I've long noticed that whatever I start writing soon gets very long!  Plus, and this may only be me, if it doesn't get to the point quickly, my mind is far away.  The fewer the words the better for me, but that may not be best for others.  I will probably try to reword things as succinctly as possible, then others can expand it if they feel it necessary.

It is always hard to get a good balance between brevity and completeness.  One mantra I try to keep in mind when writing user documentation is to try and make the key points clearly identified and stand out from the additional details that is often needed to expand on the points.

 

Almost all of your changes, I fully agreed with, often wished I had thought of it!  I did notice a few things, so just for discussion -

I initially thought I was just going to make a list of points for discussion, but then made some small 'obvious' changes and got a bit carried away.

* Nice additions at the top.  I'm still planning to expand the opening to cover alternate methods depending on which version they came from.  But I got sidetracked, multiple times, thought I would have had it done by now.

I was trying to think of points that have been raised repeatedly in the forum and see if some of them could be headed off by providing a bit more information.

 

* You added the 3 words "most users can" (into sentence beginning with "Once the backup is complete").  It feels like it's opening the door to more users using the No-format section, and we REALLY REALLY want users to format and start fresh.  I don't want to remove that section, because there will always be experienced users that want it (and you know who you are!), but we don't want anyone else using it.  However I am hoping to add more specific info to it, about the specific files to be copied over or deleted, but it's still dangerous for the less experienced to use.
I thought that it did not read well, and that the next sentence on the same point clarified who should consider using the No Format section.  I am strongly in favour of users not going down the No Format section.  In fact I wonder if the No Format section should have something like:

Expert Users Only

added at the top to make it even clearer that the No Format route should be taken as rarely as possible.  maybe the word 'Alternate' should not be part of the heading, although I understand why it is there.  In fact I wonder if it should be positioned somewhere else in the document as placing it before the recommended route seems to give it undue prominence.  Perhaps it would be better placed AFTER the section on copying Configuration files?

 

* You moved the make_bootable stuff into the middle of the Copy Files section, and reorganized it all, added some good info.  For me, it seemed to make more sense in the Final Prep section, but I don't yet know your reasoning.  (Now there's nothing left to prep in Final Prep.)  The headers don't seem right, so I'm thinking of changing them to -

  Copy unRAID files

  Make it bootable

  Install license key

  Copy saved configuration files

  Done!

You may have better ideas.

I was not think of the Make Bootable being inside Copy File - just another step I was think of getting the Flash drive into a state where the Flash drive could be used.  For me putting it early has always seemed a good thing.  One reason for putting it that early is at that point you could stop and boot off the Flash drive to check things out if necessary. 

 

Another reason is that one variant of the recommended route that is not covered at the moment (and I am not sure of the best way to include it) that I think would be worth considering including is a variant of the "Clean Install" process where you do not copy any configuration files back and simply reassign the drives to keep the data back but then set up all the remaining settings manually.  There would need to be some explanation of the fact that unRAID recognises previously used drives and keeps their existing content.    This would mean that at least one would be seeing all the current defaults and consciously changing them rather than blindly accepting decisions you made a long time ago.  This route would definitely want the user to take extensive screens shots of the current settings for reference purposes.  If going down this route you would be ready to go by the time this point in the steps had been reached. There could be a short section describing this and how to prepare for it before the step on Copying Configuration files.

 

It also occurred to me that the 'clean' install method might be relevant to those who want to jump straight from a release prior to the v5 series although that would need some validation.

 

EDIT:  Another point that has just occurred to me.  I wonder if it is worth pointing out that this could be a good time to boot unRAID 6 just to check that all your hardware seems to be recognised by v6?  This might not be the case if some users are coming from very old hardware?

 

* Concerning multiple .key files, I had put that you should only put the correct one in the config folder.  You have added that they could all be put in the config folder, and unRAID would find and match the correct one.  If you are correct, then my statement should be removed.  I'm not sure it's best to keep the keys all there, on all your flash drives, but I haven't thought this out yet (first I had heard of it).
It seemed to work fine when I tried it.  However as I only have 2 keys I may just have been lucky.

 

* In 'Meet the new GUI', you commented how different it looks compared with v5, and I had noted how similar it looked, probably because I had been using v5 Dynamix (but many others used it too).  But even the stock one seemed similar to me, same content and general layout.
I booted up the stock unRAID v5 GUI to remiond myself what it looks like and I think that the v6 one looks very different.  That is however a subjective opinion.

Perhaps we should drop any comment on how different or similar it looks, as either way it may not agree with a given users' perspective.  It's good you did it, because it gives me another perspective, that would not have occurred to me.
Not hung up on whether it is very different.  I think there are so many changes to the layout and new pages and settings that it is very different.  I have a couple of friends who are thinking not yet unRAID users but are thinking about it.  They looked at the v5 GUI and were underwhelmed, but think that the v6 one is far better.
For me, content is king, the graphical stuff tends to be almost inconsequential in comparison.
I agree to some extent, but if changing the layout improves usability then it is an improvement from a new users perspective even if the base functionality is unchanged
You see products with 'major' improvements and a hefty upgrade fee, but all they have done is move a few things around, add prettier buttons, change colors and fonts, ...  I don't see a single change in their product, but they are trumpeting major improvements (probably to justify a ridiculous upgrade fee).  But I've digressed, far away...  *Our* new GUI is enormously enhanced, a worthy upgrade!  And free!

I do not think I have ever been told I have that perspective  :)

 

* In the next sentence, you changed commas to semi-colons.  Grammatically, I think they should be commas?  (I don't feel comfortable reversing someone else's work without asking!)
I was always taught that semi-colons is the correct way to separate what are effectively a list of items in a single sentence.  Commas can be used in the right context for this purpose, but since commas are far more general purpose I do not think that using semicolons is ever wrong.  This was one I just changed on auto-pilot because it is what my grammar teacher always drummed into me as good practice. However I guess this could be something for which different parts of the world have different preferences?

 

* About the Done button, we really should press for a behavior change.  I can't see how it can be justified to leave a page without saving changes, and it constantly causes confusion, seems non-standard.  Using 'OK' and 'Cancel' might seem like copying Windows, but would make it intuitive to more users.  It's good you expanded on how it works now.  We might even want to make it stronger, with a leading 'Warning!' in red.

I cannot agree more strongly with this point.  I always find the 'Done' button is easily accidentally pressed and changes lost.  One possible recommendation for change while still keeping the current style would be that it popped up a warning about 'unsaved changes' and asked if you wanted to lose the changes.  Another possibility would be that when the Apply button was enabled the Done button was changed to read Cancel.  This would probably not be difficult to do and would make the consequence of pressing it more obvious.

 

* You added a line ("Plugins are ideally..."), but many plugins are not from LimeTech, so perhaps we should drop the "provided by Limetech".
Agree. 

I think I had in mind that using them for apps that could easily reside in a docker should probably be deprecated but I did not want to denigrate the effort that has been put into making v6 equivalents to v5 plugins.  Having said that I am not sure how well maintained application oriented plugins will be going forward - but that is just my view.

 

* Limiting 'Research & Decision making' to virtualization - doesn't seem right to me.  Plugins are still the most common addon, and probably will be for a long time.

I agree that this is the case for many of the commonest plugins.

Maybe adding the word Virtualization was wrong, but it seemed to me that most of that section was about when you should use Docker or a VM so that understanding those two concepts was key to whether they should be used instead of a plugin.

  The decisions to make are all about what should be a plugin, what should be a container, and what should be a VM.  And plugins are how we add functionality to the NAS part, the basic unRAID server part.  The NAS wants attention too!  And there are very nice plugins to add, such as Community Applications, Server Layout, Unassigned Devices, etc, all improving constantly.  We're not totally deprecating plugins, we're trying to educate users about their changed role in the new architecture.

I agree entirely - in fact I use the plugins I mentioned.  Maybe instead of 'Virtualization' something like 'Adding additional functionality' should be used instead?

 

I feel that although the section has all the key material in it that it does not read particularly clearly and could probably do with some rework to add clarity.

 

* In CacheDirs, you changed "**:" to "***", making the notes equal, but they aren't.  There are only 2 notes, each with 2 or 3 paragraphs.  I think I'll rework that whole section a bit.

OK maybe I messed that up.  One thing I have found useful in such cases is enclosing the second and subsequent paragraphs in paragraph tags as it keeps the indents and spaces the paragraphs out sensibly.

 

* You added Docker recommendations within some of the plugin carry-overs, from PhAzE and overbyrn.  Maybe it's just me, but with all the strong recommendations we made earlier, about Dockers over plugins, it almost seems disrespectful to add it again here.  They have worked hard on them, done great work, fully converted them to v6, *and* there are users who still prefer the plugins, which is their right.  My feeling is that I'm not here to tell people what to do, but to provide the best info and recommendations I can, so they can make the best decisions.  Then I should stand back and fully respect their choices.  I do understand why you added them though, could probably have added more about the risks.  But it seems too much to me, possibly becoming irritating, and it's all been said and repeated above.
Maybe you are right.    However I felt that these plugins were the ones that overlapped significantly into the application space where dockers live whereas the earlier ones listed do not.  I think that many people have so little experience of knowledge of the Docker technology that repeating areas where they should be looking at the docker alternatives still bears repetition.  Perhaps as an alternative this means a bit more should be said about docker in the Docker section of the document by giving as examples a list of the commoner applications that are available as dockers.

 

I hope you don't feel I'm being critical, I'm not, these were just items to discuss.  There were so many other changes you made (not mentioned above) that were very nice additions!

Do not worry - I am unlikely to make anything like as widespread set of changes again - I did say I had gone a bit overboard once I got started.  :)
Link to comment

Perhaps, a suggestion that most users would be advise to use plugins only that are are necessary to the operation and/or maintenance of the basic unRAID OS.  That Docker Containers and VM's should be used to provide those services which are ancillary to the basic NAS function.  The reason being that the Ancillary services require dependencies that can be conflicting with each other as well as with the base OS.  In Docker Containers, everything needed by that container is self-contained and isolated within that container from everything else on the hardware.  The same claim can be made for VM's.  Updates to one component, whether it is a Docker Container, a VM or unRAID itself, won't break anything else.

I agree with this and maybe some variant of your wording needs to be stated.  However it is difficult to clearly explain to the naïve user in how the sort of isolation provided by dockers and VM's helps maintain system stability if they have not got a background of trying to troubleshoot 'dependency hell' type issues.

 

Another point along the same lines is that dockers or VMs that are created now in v6 can be expected to run without change on future releases of the base unRAID OS (e.g. 6.1) whereas this is much less likely to be the same for plugins - particularly complex applications that may have many dependencies on particular versions of other system components.

 

The big issue is that Dockers are a brand new concept to most users and many would rather not put any effort into understanding them.  The new Docker Manager and VM Manager are huge steps along the route of users not having to understand the details.    Good guides on how to use them for common Use Cases may well help as then there are step-by-step procedures that can be used without any need to understand the underlying detail. 

Link to comment

One thing I know I did in a number of places was remove bullet points where I felt that the text did not need them as you seem to have bullet pointed nearly every paragraph.  To me that makes it easier to read, and also makes the bullet points more prominent.

Yeah, I can see that.  I guess I don't think of them as bullet points or adding prominence.  I don't use them for emphasis, I use them for organization.  But I can see I've over-used them.

 

In fact I wonder if the No Format section should have something like:

Expert Users Only

added at the top to make it even clearer that the No Format route should be taken as rarely as possible.  maybe the word 'Alternate' should not be part of the heading, although I understand why it is there.  In fact I wonder if it should be positioned somewhere else in the document as placing it before the recommended route seems to give it undue prominence.  Perhaps it would be better placed AFTER the section on copying Configuration files?

Both are very good ideas.  I'll see about moving it down to Other Topics.  Haven't done it yet, as it's a little complicated to extricate.

 

Another reason is that one variant of the recommended route that is not covered at the moment (and I am not sure of the best way to include it) that I think would be worth considering including is a variant of the "Clean Install" process where you do not copy any configuration files back and simply reassign the drives to keep the data back but then set up all the remaining settings manually.  There would need to be some explanation of the fact that unRAID recognises previously used drives and keeps their existing content.    This would mean that at least one would be seeing all the current defaults and consciously changing them rather than blindly accepting decisions you made a long time ago.  This route would definitely want the user to take extensive screens shots of the current settings for reference purposes.  If going down this route you would be ready to go by the time this point in the steps had been reached. There could be a short section describing this and how to prepare for it before the step on Copying Configuration files.

 

It also occurred to me that the 'clean' install method might be relevant to those who want to jump straight from a release prior to the v5 series although that would need some validation.

I've started the transition to adding a 'clean' install, which unfortunately means the page is a little MORE confusing at the moment, since it's only a partial transition yet.  I started with the idea of 2 types of upgrades, "a 'clean' install" and "an 'upgrade' install".  I'm closer to understanding the issues now, and it really looks like it may be best for anyone coming from ANY version prior to v5.0 to skip v4.7 and v5.0, and do a 'clean' install.  I'm open to better terminology...

 

I was always taught that semi-colons is the correct way to separate what are effectively a list of items in a single sentence.  Commas can be used in the right context for this purpose, but since commas are far more general purpose I do not think that using semicolons is ever wrong.  This was one I just changed on auto-pilot because it is what my grammar teacher always drummed into me as good practice. However I guess this could be something for which different parts of the world have different preferences?

I was rather surprised by this, by your teacher!  It goes against everything I have ever learned about them, or ever seen, so I'm going to have to research it, perhaps I've been wrong all my life!  Or perhaps it's a regional thing...

 

There is also information that is likely to help those who are trying to help those who have customized their existing unRAID system beyond its basic NAS functionality.

Can you rewrite this sentence?  It's not clear if you are referring to helping those with customizations, or helping those who help those with customizations, or maybe it's both!  But also, do you think this sentence is necessary?

 

I'm not crazy about all the additions to the top, because it feels like it's becoming a preamble.  I prefer the absolute minimum, and then get straight into what the user is here for.  But that's me, it's good that you and others are involved to balance me.  Me, I'd chop out maybe 70% of it.  All the extra explanations seem unnecessary, makes the page that much longer.  The more we add at the top, the sooner they zone out farther down and stop reading.  Just my opinion...

 

The license key stuff was good, and I added to it, reorganized it, then thought that most of it is descriptive, not implementational.  So I moved most of it up into the Important Considerations section, and just left the implementation parts.

 

Lots more to do ...

Link to comment

It also occurred to me that the 'clean' install method might be relevant to those who want to jump straight from a release prior to the v5 series although that would need some validation.

I've started the transition to adding a 'clean' install, which unfortunately means the page is a little MORE confusing at the moment, since it's only a partial transition yet.  I started with the idea of 2 types of upgrades, "a 'clean' install" and "an 'upgrade' install".  I'm closer to understanding the issues now, and it really looks like it may be best for anyone coming from ANY version prior to v5.0 to skip v4.7 and v5.0, and do a 'clean' install.  I'm open to better terminology...

I agree that a 'fast route' to v6 without intermediate steps seems a good idea if coming from a pre-v5 release.  There have been a number of people asking about this in the forum so covering it makes sense.  It is also not a bad route for those coming from v5 who should revisit decisions they made some time ago.  Will keep trying to think of 'better' terminology.

 

I was always taught that semi-colons is the correct way to separate what are effectively a list of items in a single sentence.  Commas can be used in the right context for this purpose, but since commas are far more general purpose I do not think that using semicolons is ever wrong.  This was one I just changed on auto-pilot because it is what my grammar teacher always drummed into me as good practice. However I guess this could be something for which different parts of the world have different preferences?

I was rather surprised by this, by your teacher!  It goes against everything I have ever learned about them, or ever seen, so I'm going to have to research it, perhaps I've been wrong all my life!  Or perhaps it's a regional thing...

I checked on Wikipedia and that says that both comma and semi-colon are valid separators for list items in a sentence.  It mentions semi-colon as being of particular use when the list items themselves contain commas, or the sentence contains commas that are not being used as list separators. 

 

Sounds very much like something that could vary by region or even personal preference.  I checked a company document I had aimed at technical writers writing software manuals and that mentioned semicolons as the preferred practise as it was never ambiguous (but also said that was not a rigid guideline but just a suggestion and the author should do what 'felt right').

 

There is also information that is likely to help those who are trying to help those who have customized their existing unRAID system beyond its basic NAS functionality.

Can you rewrite this sentence?  It's not clear if you are referring to helping those with customizations, or helping those who help those with customizations, or maybe it's both!  But also, do you think this sentence is necessary?

Even I could not make sense of it and I wrote it :)  I have chopped out some of the redundancy so now it should make sense.    I would suggest that anywhere you notice a sentence getting confused like that one you just chop out the redundant words as the result is certain to be easier to follow.

 

I'm not crazy about all the additions to the top, because it feels like it's becoming a preamble.  I prefer the absolute minimum, and then get straight into what the user is here for.  But that's me, it's good that you and others are involved to balance me.  Me, I'd chop out maybe 70% of it.  All the extra explanations seem unnecessary, makes the page that much longer.  The more we add at the top, the sooner they zone out farther down and stop reading.  Just my opinion...

The reason I thought a little preamble is a good idea is that many (most?) of the users that are likely to use this guide are those who have not kept up with what has been happening during the v6 development cycle, and may well not have touched the setup of their system for years.  A few (short!) positioning paragraphs might help convince them the guide is relevant to them and worth spending time on.  I do, however, get your point about concentrating on the basics and trying to keep the eye focussed on what is the goal.

 

One idea might be to use multiple pages to cover all the material.  This would not shorten the overall amount of text but might make it easier to navigate and follow the basic process.  As an example one could put the sections on customising settings and installing plugins onto their own page and the top level page just refer to these as steps to be carried out.  It would keep the top level process cleaner while still providing a repository of useful information about the finer detail.

 

The license key stuff was good, and I added to it, reorganized it, then thought that most of it is descriptive, not implementational.  So I moved most of it up into the Important Considerations section, and just left the implementation parts.

Good idea.  I originally added the license key stuff thinking about the users coming from the 'free' v5 license who might not have understood the implications of the change in the licensing model and would find they could not start their array because they infringed the 'attached devices' limit.  Perhaps that special case should just be emphasised and the detail should just be handled by giving the link to the Limetech provided pages on the main web site?

 

Other thoughts:

 

I was wondering if the Research and Decision Making section material should be also be positioned under the Important Considerations category (and possible slightly reworked with that change in focus in mind).  It feels a bit clumsy where it is at the moment and detracts from the flow of the upgrade process.  What do you think?  Another possibility is putting it under the '''Other Topics''' part of the document if you want to keep the main process flow less cluttered.

 

Also in the Important Considerations section I think it would be worth formatting it so the each bullet point starts with a bold 'title' that summarises that point and then explanatory text.  That way someone skimming that section might at least get a feel for the areas that are covered without reading all the text.  Do you want me to make the (small) adjustments to conform to that style?

 

The '''VM Images''' section feels 'sparse' at the moment.  Perhaps as well as guiding the user to the relevant part of the forum it should also provide links to some the excellent articles and videos that JonP has been producing covering this topic area?  The JonP articles may well now provide a better starting point than diving into the forum KVM area?

 

The '''Go File Items''' feels a bit out-of-place where it is.  Maybe it should be much earlier in the document? Maybe as high as just before the '''Meet the New GUI'' section?

 

Link to comment

/extra - keep or delete
     * - delete all files and folders

 

While I understand what you're trying to accomplish here, I can see how a new user might get confused  by this...  You've got one line saying to keep or delete the folder, and the next line saying to delete the files.  (Just posted the one example line)

 

IMHO, I would make it super simple and just have them delete the entire folder period.

Link to comment

I need others to review for accuracy the new Files on flash drive section of the guide.  There have been several requests for info on exactly what can be kept and what has to be deleted, so I've tried here, but it's tough, as things have changed over our long history.  There are 2 items near the bottom marked with question marks.

 

RobJ, you have undertaken a noble effort but I am afraid that this section will actually cause more problems than it solves.  It seems to contain a mix of old and new folders--New ones that are new to (and required by) version 6 and Ones that may have been placed there by either earlier version of unRAID or by the user as they installed plugins.  This makes it an extremely confusing read even for someone who is reasonably familiar with what should be there. 

 

First thing is that the list needs to reflect exactly which files and folders are required by a version 6 'virgin' install and their location. 

 

Second thing, it needs to indicate the files and folders that were placed there by early versions of unRAID.  Then there needs to be an comment as to whether this file can be used by version 6.  These would be primarily the configuration files that will properly configure the server to 'look and feel' like the old setup.  The 'go' file and the 'syslinux.cfg' files should be treated as special cases to indicate that editing of them may be required to implement certain configuration changes.  (As a complete aside, I don't believe, there is any explanation in this WIKI about how to edit the syslinux.cfg to change the default boot selection.  This section should probably be called something like 'Change Default Boot Option'.)

 

Third thing, there need to be a list of files and folders which might be there that are likely to cause issues with Version 6.  Most likely these folders were created either directly by the user or by some plugin that the user installed.  This section will have to describe what to do with these files.  This may a big problem area as the issue of where to put folders and files was not defined until fairly recently and even then I don't know how many plugin writers observed these recommendations. 

 

In any case, that is my two cents...

 

Frank

Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.