User Manual Organization

[rdenney]

I can't seem to find a forum that fits this, so I'll put it here and beg the forgiveness of the moderators if they feel it needs to be moved.

 

It seems to me that the user manuals are leaving new users somewhat in the dust as to what information is correct and to which version it applies.

 

I posted an issue about finding a disk to be unformatted after adding it to the array. Just so you guys who know this stuff can see this from the perspective of an idiot (ref: Napolean's Fool*), allow me this tour of the various manuals:

 

The Official Manual, which claims to be authoritative, says this:

 

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.

 

The Version 5.0 Beta Manual says this:

 

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.

 

Since I'm using the latest version, which is a 5.0 release candidate, that's what I thought should have been the appropriate instruction.

 

But the plot thickens. My drive shows as "unformatted" on the Main page, and an hour spent trying to sort through various documents on the Wiki and in the forum revealed nothing except warnings, so I posted a question on this forum. To which, the answer was a polite version of "you have to format the disk after adding it to the array". Any new user could be forgiven for reading in the above that the formatting should take place automatically. So, I explored further this morning after a night's sleep and recovery from being tired and frustrated.

 

The Unofficial Manual (which claims it's unofficial in bold red type right at the top), says this:

 

When you Start the array, the system will show newly added disks as "Unformatted" If any disk shows as Unformatted a "Format" button will appear on the management interface. You must press this button to 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.

 

That "format button" was certainly not in plain view when I looked for it last night. I'll look again tonight. I don't think I missed it, but it wouldn't be the first time. I was sure looking for something like it, figuring there must be a way to reformat a disk with NTFS or something else on it already.

 

Then, the How-To section reads:

 

Go back to the main unRaid management page, if the drives are new, or if they have any other file-system other than reiserfs, they will appear as "unformatted" You will need to check the checkbox to format them. this will erase any data that was previously on them by first clearing them and then partitioning and formatting them with a reiserfs file-system.

 

So, now it's a check box. I don't remember seeing that, either, but I'll look once I'm back in contact with the system.

 

It would be nice if entries to the various manuals did two things:

 

1. Provide the date they are entered. People might have to actually write this down in the article when they include it in the Wiki rather than try to dig it out of the Wiki software.

 

2. State which versions it applies to, even if it's "up through version X" so that people will know to keep looking if they have a newer version.

 

The Wiki page on the How-Tos does suggest at the top that it needs to be incorporated into the manual materials, and more thoroughly linked, and I know that everyone has ideas but few have willingness to take something on. But the outcome is that the "official" manual for Version 5.0 Beta (which any new user would think applies to the latest release candidates) is, in fact, incorrect and misleading to a new user, and the correct information about this basic task is quite hidden from view.

 

* Napolean's Fool is a story about how Napolean kept a person close to him who was ignorant (not stupid) of his intentions, and he would have his Fool read his instructions to his generals before dispatching them. He would never explain the instructions, but if his Fool did not understand them, he would rewrite them until he did. This issue has certainly made me feel like a Fool 

 

Rick "respectfully submitted" Denney