Remove the manual from website and port to wiki

[NAS]

There is a bit of a information location disparity. We have a plethora of info in the forum which is slowly being documented in the wiki. Then we have the website which has the official documentation.

 

None of the sources are definitive by themselves and you can glean new info by reading all three.

 

IMO all the manual should be ported to the wiki. The community can add to the documentation as it already is with the wiki in general and it is a far better platform for documentation anyway.

 

Centralised documentation should be the cornerstone of any project.

 

I will happily start/complete the work given the go ahead.

 

Version control and peer review will ensure the manual stays accurate, one thing this project is not short of is smart contributors. If polution becomes a problem then the page can be locked or ranks setup.

[NLS]

I agree.

 

Things are a bit "yesterday" on that front.

Doesn't bother the experienced users, but easily scares the new ones or even the POTENTIAL customers (something I have stressed a few times - being in the field quite a few years). Let's hope now that Tom moves to "full time unRAID", someone will be there to take care of such "little details".

 

(yes I know I use too many quotation marks)

 

 

[limetech]

NASUser - you have PM.

[NAS]

I have started the work. Im doing most of this offline on my personal wiki to save the official one from hundreds of change logs.

 

My plan if to redo quite a bit of the wiki structure to make more sense in the context of Official documentation and unofficial stuff. If i find duplicated data I will delete it from the wiki if it makes sense that it is held on the homepage etc.

 

Nothing too radical will be done and deletions will be made rarely and with careful considerations.

 

Tom can you look at perhaps bumping my wiki rank to one that can lock pages. My plan is to tout the official documentaion as a "must read" shorter set that is essentially unchanging. The the rest of us can go mad adding other stuff to other pages for the more adverturous user. The key is to make it clear new users that using unRAID is easy and that all these hacks are just that.

 

Will post when I am complete.

[NAS]

Phase one complete. There are still lots of formatting errors etc but the general copy over and shape is there.

 

Thoughts so far?

[jasper9890]

looks good so far BUT i dont see the overall "Recent changes" link anymore.  I liked bringing this up periodically to see what updates have been made.  Any chance we can get this back?

[NAS]

Its under the specials section:

 

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

 

along with sorts of other goodness. This is where it lives in all mediawiki installations by default

[limetech]

looks good so far BUT i dont see the overall "Recent changes" link anymore.  I liked bringing this up periodically to see what updates have been made.  Any chance we can get this back?

 

Yeah - I removed that - got a little "overzealous" cleaning up the Navigation box I guess 

[jasper9890]

ahh thanks guys, you rock 

[RobJ]

Great work, a very good start!  This kind of work is often very thankless, in spite of being so important, and requiring so much time and thought.  I would like to express my own appreciation for the time put in so far, and your efforts in the future too.

 

Please don't let my comments below in any way lessen my appreciation of the quality of the work done so far.  It is not based on much content review, but just some initial impressions.

 

I'll start with this page:  http://lime-technology.com/wiki/index.php?title=Official_Documentation.  For my thoughts on the page title, see farther below.

    * unRAID Manual - Interface Main
    * unRAID Manual - Interface Users
    * unRAID Manual - Interface Shares
    * unRAID Manual - Interface Settings
    * unRAID Manual - Interface Devices 

The first thing I notice here is the redundancy, but I'll get to that.  The next thing that stands out is the word Interface, which feels somewhat foreign here.  It is a very good word, and I like it, but it is not a word that we ever use in connection with unRAID, and is not included in the linked pages either.  I suggest replacing unRAID Manual - Interface Users with something like unRAID Manual - Web Management interface - Users.  The unRAID Manual calls it 'a browser-based Management Utility', and technically that is correct, however to most people, it's a Web page.  Even if they have often entered data into web forms, and shopped and banked online, most users won't think of a Web page as a program or utility.  I would prefer calling it the Web Management interface.

 

Then I would remove the redundancy, by making unRAID Manual - Web Management interface a heading or something, and make the bullets just the single topic word, associated with the Web page tabs.  It is easier to relate the single word topics to the single word Web tabs that way.

 

The page that, I have to be honest, I really don't care for, is the start page for the unRAID Wiki, the top page, the first Wiki page anyone comes to:  http://lime-technology.com/wiki/.  It used to be a friendly and helpful page, but rather informal, incomplete, and not particularly professional, but the most important links were there.  Now, it is brief, unfriendly, with a legal feel, condescending and wary toward user contributions, and if you need help, misleading and unhelpful.  The most important and common reason (in my opinion) that people come to the Wiki is to get help, troubleshooting help (again, in my opinion).  This could be partly remedied by adding a section of commonly used links, call it Popular Links, Favorite Pages, Important Links, Most Read Links, whatever, or add it to the existing Useful Links.  I would make the Troubleshooting page the very first link, then add the Hardware Compatibility page, and some of the specific How-To's, like 'Copying data from an NTFS disk', and the FAQ, once it has some meat to it.

 

Now, I can understand why the start page has changed the way it has, and technically it's a good thing and correct, but it just feels so wrong.  It feels like Lime Technology has hired a legal team to write it.  Personally, I feel the lawyer folks should keep their mitts off the main pages, and stick to writing fine print, little disclaimer boxes, and the linked license, privacy, and EULA pages, and perhaps now and then review all content.  In other words, the warnings on this page about the possible inaccuracy of user-generated content are important, but very off-putting.  My first impression from this page is not about how or where to find help, but that there is OFFICIAL Documentation, and there is (spoken with a condescending tone of voice) very unofficial and unreliable user written stuff, that cannot be trusted.  So if I come here with a problem with my unRAID server, needing to find a quick solution to my problem, I don't want to spend much time reading manuals, and I learn quickly that I sure don't want to read that user stuff, so I turn to the Official Documentation - and get almost nothing!  I won't easily find or trust the TroubleShooting page.  The unRAID Manual is fine when you are first learning about unRAID, and later for reference, when you don't understand how to do something, but it is not currently useful when something goes wrong.

 

For now, I would have to disagree with the 'fault find' part of this statement:  Official documentation should be your first port of call when learning to operate unRAID or fault find a problem.

 

There is no reason you can't keep small disclaimers and cautions, but the page needs to be inviting, friendly, and helpful.  I would prefer changing Official Documentation to unRAID Reference Manual, or Official Guide to Installing and Using unRAID.  It still sounds 'official', but is more helpful, and doesn't sound so officious, about itself or that other 'unofficial' stuff.  So long as there are cautions included about possible errors in anything not Lime Technology written, then I don't think the 'Official' distinction is that important.  The theme of this page should be about all of the different sources of help, not how careful you have to be while reading it.  It just happens that currently, almost all of the troubleshooting and equipment pages are user written, but that does not make them any less important.  I suggest removing the Official Documentation and Unofficial Documentation headings completely.  I don't know the best way to work it, but I would like to see this page both as an intro to unRAID and as a Table of Contents to all the different sources of unRAID information.  I think I would like to see it include the Overview again.  A good unRAID system picture might be nice.

 

I apologize for getting carried away.  I honestly do appreciate all of the work put into this.

 

[NLS]

great job

 

 

[NAS]

Bit busy to answer this now with the kind of depth that was posted earlier, will do so tomorrow.

 

I totally understand where you are coming from but in essence i dont agree at all with the "feel" thing. I think it  is absolutely vital that the homepage feels official and clinical and that the split between official and unofficial is also clear and precise.

 

Once into the Unofficial section it can again be an information free for all with all the dynamic user contributions evolving it to become an excellent resource but I can say with absolute certainty that a technical wiki written by committee with no real peer review or fact checking will not suit all reviewers. Keep in mind a new user who doesnt know linux is now coming to the wiki as the manual. They need hand held and cant be left with any feeling of doubt.

 

This now there are perhaps 5 people that write on the wiki but in time that could be 500. As it expands a clear distinction between Official relatively brief documentation and the information barrage of user defined documentation needs to be exact. A new user need to know at a glance from the home page why there is such an info disparagy.

 

Put another way consider the home page as a menu between two wikis and the un official one can look just like before if needed.

 

As for the page names please keep in mind this is Alpha and still being reviewd by myself and in time Tom as well.

[WeeboTech]

I like the idea of changing it to "unRAID Reference Manual" or "Official Guide to Installing and Using unRAID"

 

Perhaps unofficial could be defined as User Contributed Documentation

I also like the idea of Popular Links, Important Links, Most Read Links

 

I think the use of Official Documentaiton should just be changed to "unRAID Reference Manual" as it always points back/references the product itself.

 

When I first read "Official documentation should be your first port of call when learning to operate unRAID or fault find a problem."

I thought what???  Perhaps fault find should be troubleshoot.

 

So far the text inside the "unRAID Reference Manual" looks good.

I think screen snapshots of the associated browser page would go a along way in each section.

 

[NAS]

I still disagree. If this was a typical open source project I would be with you on this but it isnt, its a commercial product with a GPL spin. I think in that light calling the Official documentation "Official" is completely acceptable since its a product of Limetech LLC.

 

I will look at it again though in light of the comments but I really think that if we start having "unRAID Reference Manual" and then the same info written by someone else in another section it will get confusing for users who dont care about anything other than getting it in and moving on.

 

Fundamentaly a new user has to be able to skim the homepage and understand why some pages on the wiki are detailed and some others have one line.

 

They also have to understand that as soon as they go outside the official documentation that they are in less supported territory.

 

In my opinion this is really just semantics since its a new way to look at it. Users will use search and read whatever it returns (aka its only us that will care about the sematics of the naming).

 

When I first read "Official documentation should be your first port of call when learning to operate unRAID or fault find a problem."

I thought what???  Perhaps fault find should be troubleshoot.

 

No the official manual should be the first port of call. Its OK for us who have read and understand the manual but most users wont have so in order for Limetech to support this product it needs to be clear that user refer to the manual.

 

You are totally correct about snapshots I agree it would make it much better. But the only changes I have made to Limetech LLCs documentation has been one of necessity due to format differences and other limitations. We cant just randomly decide to add stuff to the official manual and Limetech has to support it.

 

Perhaps I am being far to anal about this commercial GPL split but until I get clear instruction from Tom on behalf of Limetech Im not going to randomly decide my way is better.

 

Also as the wiki grows and editors and more importantly reviewers grow we can look at this again.

 

Edit:

 

I reread my post and it comes across too much like "I am right and everyone else is wrong". This is not my intention.

 

I am simply saying:

 

Give it time, its only alpha this now.

unRAID is a commercial product which makes the wiki more complicated to present correctly.

Things can and will change once the wiki gets some more editors, reviewers and support use. When this happens it will naturally evolve.

 

Until then I recommend we go with what we have and concentrate more on adding content and using the wiki links in this support forum that worrying about the "feel" of it. At this point the homepage has only been viewed a total of 287 so its not really in use yet at all.

 

[WeeboTech]

Perhaps fault find should be troubleshoot.

 

fault find implies there are faults in the system.

Troubleshoot is more of an industry standard,  defining a state of resolving a problem.

 

I've never seen any official documentation define a fault finding guide.

I have seen many commercial products with a separate guide on troubleshooting.

 

 

They also have to understand that as soon as they go outside the official documentation that they are in less supported territory.

 

I think this is a bad way of thinking. It's the community that is helping to support the product.

Tom even said it in a message over the past few weeks.  How he lets the community answer the redundant questions.

If there is documentation making it to the wiki without being reviewed and sanctioned then that's a problem waiting to happen.

[Joe L.]

No the official manual should be the first port of call. Its OK for us who have read and understand the manual but most users wont have so in order for Limetech to support this product it needs to be clear that user refer to the manual.

<snip>

We cant just randomly decide to add stuff to the official manual and Limetech has to support it.

I would like to make one suggestion as to where it might be appropriate to "add stuff" to the official documentation, and that is when the official documentation is no longer accurate (it describes behavior of an early version of unRAID)  An example is the "official" description of adding a new drive to expand the array.  It does not mention the "Devices" assignment page.  It also seems to say that the new drive will be formatted and cleared as soon as you power up the array.  This is not accurate.

 

In cases where the official documentation is out of date, or incomplete in its description (Tom understood it, but a completely new user to the product might not) I would suggest some style of temporary notation in the wiki that would indicate the "official text" is appropriate to an earlier version unRAID, an update to the wiki to a more correct current description, and a note to Tom to review the correction.    In some cases, both descriptions will be appropriate, with a "version" sub-heading for the affiliated text.  We must remember that there are still people out there with version 1.x of unRAID running their servers.

 

Joe L.

 

[SSD]

A couple of general comments.  None of this should in any way be construed as a criticism of the work to date.

 

1 - It is important that the "official documentation" be a dependable source of accurate information about the latest production version of the product.  It also has to look good and "feel" official.  As a relatively recent purchaser (just a few months ago), I have to say that the quality of the documentation was an important factor for me purchasing a product based on an OS I did not know.  Although brief, it was well-written and authoritative.  If I got the impression that the official documentation was some sort of community effort and not 100% authoritative, it would have impacted my decision to buy at that time.

 

2 - I'd like the official documentation to reference the current release of the product (non-beta).  Update access should be restricted to Tom and a small set of designees.  But I would suggest a section that contains a complete DUPLICATE of the official documentaiton.  Through the beta cycles, Tom as well as community members could contribute content to the beta wiki area.  As the final beta becomes the official release, Tom (or someone) would review, revise and supplement that documentation.  This would allow the community to contribute to the official documentation but subject to Tom's final check for accuracy and appropriateness.  Contributors would have to be "ego-less", as it would be Tom's call as to what belongs in the official documentation.  Afterwards, the official documentation and the beta documentation would be in sync.  (I'm not sure if wiki supports this type of model).

 

3 - The "unofficial" portion of the wiki needs to be monitored for accuracy.  When I first started using unRAID, I found stuff in there that was old and no longer applied.  It was frustrating to try things that didn't work.  There were no version numbers anywhere to let a reader know what version it was tested on.  Lacking this type of diligence, the wiki is not something that users (esp new users) will have a high degree of confidence in.  I guesss this is a common problem, but not sure if there is a good solution.  Just having people enter version numbers as to the version of unRAID they are using when the material is submitted would be useful IMO.

[Joe L.]

All good points... but it reinforces my thinking that there is also a need to document the older releases, or at least how they differ.  In other words, if the documentation talks about the "Devices" page it will completely confuse anybody on an early version of unRAID as that page did not exist.  Device assignment was done in a config file. 

 

So... perhaps a "legacy documentation" section should exist for those who have never upgraded their unRAID os, but now want to expand their array with a new drive, or find the need to replace a failed drive.  The steps are not exactly the same, and honestly, I know I do not remember what the screens said "exactly" back on version 1 or 2 of unRAID to help them.  It was not possible to load your own flash drive back then.  Tom only sold them pre-loaded.  He used "grub" and not "syslinux" as the boot loader. It almost is a task onto itself to describe the differences.  Somebody needs to boot onto older versions, verify documentation on how to add a drive, replace a drive, and how to upgrade to the current version. 

 

Joe L.

 

 

[NLS]

To be honest I haven't read the thread line by line, so I probably miss something.

 

What I wanted to comment is on the last post by Joe.

 

Why would someone care about people with an early unRAID version?

Why I am so rough:

 

1) Companies rarely keep old versions of their documentation on line. Usually you find the docs for the latest version. This goes in contrast with actual software, where companies SOMETIMES do have older versions online. Even in this case, LimeTech has just ONE older version online.

 

2) When those people purchased (or just used the free) unRAID "older" version (which was current back then), there was no real documentation (or not at all), so why would someone warranty something like that now?

 

3) What prohibits them from upgrading and why would this bother everybody else?

 

...those aside, if someone wants to spend the time to install an old version (that is not even available for download) and write extra docs specific to that, nobody prohibits adding a separate section in the docs for such users. I wouldn't want time taken from the main project though.

 

My 0.005c.

 

 

[WeeboTech]

Why would someone care about people with an early unRAID version?

 

People who are still running an old version.

Unless There is some official statement of when a supported version no longer becomes supported, then the documentation should exist somewhere.

At least when you purchase a software product old or not, it has a document for it being either hard copy,r TEXT, HTML or PDF.

 

If the documentation were TEXT, HTML or PDF then a person could tuck it away.

 

So now we're going with a complete online version.. I see that as good.

Therefore, versions of the documentation should exist for supported versions of the software.

I haven't seen anywhere a post stating which versions of software are being sunset or removed from support.

 

Companies rarely keep old versions of their documentation on line.

 

Depends on the company, the software and how the product is disseminated.

Our IBM products have 4 revs of documentation online.

 

This one has two.

http://www.serverelements.com/documentation.php

 

 

 

What a strange unfriendly feeling here lately.

 

 

Who is really supporting the product? Tom alone or the community?

 

If the community has recommended keeping older information around to help people, what harm does it have keeping it around until it is officially unsupported?

 

[NLS]

My whole "issue" is that there is no real reason people still use an old version (except maybe bored to upgrade).

Or is there?

 

Because if I am correct, write a nice "please update" and don't spend hours writing obsolete documentation (its not that the documentation is somewhere and just needs some cleanup and conversion... it needs to be written from scratch).

 

In any case, my previous "1, 2, 3" post was clear enough (for my bad English).

 

 

[SSD]

There is a certain beauty in having .PDF style documentation that can live on forever as the definitive source for each version.

 

With this style of "live" documentation, I don't think it is unreasonable to expect people to keep up, or deal with slightly out of date documentation if they lag behind.  Upgrading is free after all.  I think that has been the "de facto" model.

 

Any thoughts on #2 below?

 

A couple of general comments.  None of this should in any way be construed as a criticism of the work to date.

 

1 - It is important that the "official documentation" be a dependable source of accurate information about the latest production version of the product.  It also has to look good and "feel" official.  As a relatively recent purchaser (just a few months ago), I have to say that the quality of the documentation was an important factor for me purchasing a product based on an OS I did not know.  Although brief, it was well-written and authoritative.  If I got the impression that the official documentation was some sort of community effort and not 100% authoritative, it would have impacted my decision to buy at that time.

 

2 - I'd like the official documentation to reference the current release of the product (non-beta).  Update access should be restricted to Tom and a small set of designees.   But I would suggest a section that contains a complete DUPLICATE of the official documentaiton.  Through the beta cycles, Tom as well as community members could contribute content to the beta wiki area.  As the final beta becomes the official release, Tom (or someone) would review, revise and supplement that documentation.  This would allow the community to contribute to the official documentation but subject to Tom's final check for accuracy and appropriateness.  Contributors would have to be "ego-less", as it would be Tom's call as to what belongs in the official documentation.  Afterwards, the official documentation and the beta documentation would be in sync.  (I'm not sure if wiki supports this type of model).

 

3 - The "unofficial" portion of the wiki needs to be monitored for accuracy.  When I first started using unRAID, I found stuff in there that was old and no longer applied.  It was frustrating to try things that didn't work.  There were no version numbers anywhere to let a reader know what version it was tested on.  Lacking this type of diligence, the wiki is not something that users (esp new users) will have a high degree of confidence in.  I guesss this is a common problem, but not sure if there is a good solution.  Just having people enter version numbers as to the version of unRAID they are using when the material is submitted would be useful IMO.

[NAS]

I have started to tweak the wording to be less "harsh" describing the Official and Unofficial versions. (give me time to work it out

 

I was particularly happy to see bjp999 post as the voice of a newer user which reinforced my own thoughts that there needs to be a clean break between virtually static official documentation and user submitted stuff.

 

I also had not even considered old versions of unRAID. This proves an interesting quandary that only Limetech can answer... what versions are supported.

 

Obviously if someone turns up with an old version they will get help cause help is what were all about... but that doesn't necessarily follow that Limetech officially supports all old versions. Sure in a perfect world we all could but making sure documentation reads relevant for every version ever made would be a thankless task and IMO make the wiki far too confusing.

 

Now one nice point of the wiki is change control so there is not reason why we could make a major version change and tag it "Manual for 4.2" and then keep adding to it for "4.3". Then we can link to the old version in the official summary page. This is probably nicer than having umpteen copies of the same manual about.

 

I also totally agree with the comment that the manual has "errors" or at least areas that we could improve. This one is a balancing act since opening it for all to edit means there is a HIGH probability that more errors are introduced. Not all editors will be as technically competent as you guys.

 

Also we dont want some moron adding "rm -rf" to the official manual and some poor sole following blindly before we spot it. For that reason alone i think we need to come up with another way of doing it/peer reviewing than opening it to all. Also i cant get away from the fact that whilst we all want to help the buck stops with Limetech as a company and we should keep that in mind.... should a company have a fit and want to retaliate due to a failure or the like its not us that they are coming after.

 

 

On a final note this is the third time Ive had one fo these wiki conversations on various projects and this one is getting about as passionate as any of them. Thats a good thing! More input can never be bad.

 

[Joe L.]

My whole "issue" is that there is no real reason people still use an old version (except maybe bored to upgrade).

Or is there?

Every few months, somebody starts a thread with... I'm on the original version of unRAID, it has been working for me for years now..., I now need to...

(upgrade, repair, replace, fix, recover)  ...

 

The reason they did not upgrade is that the server worked for them, and they saw no need to upgrade.

Because if I am correct, write a nice "please update" and don't spend hours writing obsolete documentation (its not that the documentation is somewhere and just needs some cleanup and conversion... it needs to be written from scratch).

It is a LOT more difficult to upgrade from the original version of unRAID.  The superblock was on a hidden second partition on the flash drive that Tom provided.  The original owner did not load the flash drive themselves.  Tom sold the flash drives loaded, or fully built systems.  We did not download and install software on our own flash drives we purchased at the local store.

 

In other words, those original owners are completely unfamiliar with today's version of unRAID unless they have upgraded as each new version has been released.  For the most part, the old versions did exactly as they were supposed to, they stored data and provided disk shares.  There were a few bugs involving adding new disks that eventually got fixed, but they affected people who were replacing a defective drive... or swapping parity with a larger drive.  Those activities were rare on the older versions, we were still adding drives to the arrays, and not replacing defective drives yet, as the servers were no online that long.  There was never a bug in storing the data, so... many people have never upgraded.

 

With that in mind.. some documentation on how to upgrade is probably in order.  Tom has it mostly in the release notes... Unfortunately, when an original 1.x version user comes to the wiki now, many times their array is broken, they are in need of a new disk, and they are having a difficult time.  I don't think the instructions on how to read the hidden second partition on the original version flash software is even anywhere in the official documentation.  It might be in a release note on an early version of unRAID, and it might have a link to a page that no longer exists.    They do not want to lose their data, and they do not want to completely re-do their flash drive when their server has a failed disk.    The documentation might be as simple as saying.. Ask for help, describe your problem on the forum, and do NOT reset your array by using the "Restore" button if you have a failed drive.    In fact, the forum did not exist back then, and the user reading the wiki might not know about it.  Most of the time, all they need is guidance.  Most of the time, if there is no documentation describing how to proceed, we are very helpful in working them through their issues.  Many times we want them to upgrade, but their array is broken, and it is not the right time for that step. We must first get them working, and then get them to upgrade.

 

A section in the wiki on HOW TO UPGRADE YOUR UNRAID SOFTWARE is probably in order.  The instructions will be very different for those early users of unRAID then those with a current version, as they will need to take steps to avoid having to completely re-calculate their parity drive when first booted.   

 

Many of us will help to put the documentation into place once the basic structure is there.  What you have done so far is a great start towards that end. 

Please do not let this critique get to you, but there are many perspectives and target audiences.  I just think we need to think of how to make the document useful to everybody, not just current users.

 

Joe L.

[WeeboTech]

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

 

I'm not suggesting to re-write old documentation. Make what ever exists, available via hyperlink.

However, I would suggest keeping it around (in whatever format it exists until it' is officially "unsupported".

Even then a hyperlink to an old doc/txt/html/pdf is a courtesy.

 

The tone of the prior statement was, not to even have it available. My thought is, it should be available until a statement of sunset is given.

 

In larger companies when a new release is produced, there is a statement of when an old release is unsupported (or declaration of earliest release of support).