Troubleshooting User Manual -- Should We Create It?

[joeschmuck]

So there are an awful lot of simple small errors which occur very frequently. Should we create some troubleshooting guide to help people along? How many hard drive failures or SATA cable issues, RAM failures, MB failures, or even configuration errors which may seem like a hardware error.

I wouldn't mind spinning up a simple troubleshooting guide for these routine things and reduce the repetitiveness of answering the same thing over and over again. I would only caution that if we do this, it must be kept simple and easy to follow. If we get too complex then some folks will not be able to follow it. Also we need to know when a problem should be asked in the forum so the guide wouldn't cover every problem, I wouldn't want it to, at least initially.

Just asking for opinions on this. I plan to write one called "Is My Hard Drive Bad?" but it will take me a few days to do it because it takes time to do a good job. I can create it as a new thread or PDF, or any other format. We might even be able to open a new section on the Forum called Troubleshooting but only authors would be able to edit that section.

Cheers!

 

[dlavigne]

+1 from me. Especially since the 10.x series will only have built-in help (eg not a formal HTML guide). My vote is for it to exist as a subforum as that's where the 10 stuff will be going (for the stuff that doesn't fit/belong in the built-in docs).

 

[Mirfster]

Sounds like a good idea, but I think something like this should be included in the actual manual itself near the end. This way it helps to insure that people have been presented the per-requisites prior to just jumping straight into troubleshooting.

I am fairly new here and aside from the FreeNas guide/manual there are tons of great stickies that help just as much. While I don't mind searching and reading the various threads, others may overlook doing so and end up thinking to reference just the "Troubleshooting Guide" in the belief that this is the "magic bullet" that will fix their Laptop running FreeNas with 2 GB of RAM and 4 USB Drives connected to a USB 3.0 Hub...

True that the "Troubleshooting Guide" may have a designated section on "Hardware Requirements", but then it would also mean that the information would need to be maintained/updated in multiple places (or could just have a link saying "Go see this post"..).

I see the logic to address reoccurring questions and totally agree with that, but lean towards the idea that it would be more beneficial in the long run to point them to the "Troubleshooting Section of the Manual" instead of the "Troubleshooting Guide".

+1 from me. Especially since the 10.x series will only have built-in help (eg not a formal HTML guide). My vote is for it to exist as a subforum as that's where the 10 stuff will be going (for the stuff that doesn't fit/belong in the built-in docs).

Is that due to time constraints right now or is it a decision to not have it at all going forward?

 

[dlavigne]

Is that due to time constraints right now or is it a decision to not have it at all going forward?

It's the decision going forward to help streamline the docs and decrease the getting up to spped reading curve. Right now the manual is a monolithic 300+ pages and basically says what is in each screen. This is a sad necessity due to the non-intuitiveness of the GUI. Beginning with 10, the GUI will be more intuitive and workflow-based and will have 2 types of built-in help. A short help (similar to the tooltips we have now) for each knob and a longer contextual help (eg that provides an overview of what you are accomplishing and why such as creating a storage pool or creating a Windows share). Everything else would be a how-to which really belongs in the forums and which we really don't have in the great big Guide.

 

[joeschmuck]

I agree that a troubleshooting guide would be best placed in the User Manual eventually however we can start it in the forums for now.

@dlavigne could you setup a section under Documentation called "Troubleshooting Guides" and then make it so no one create a new thread except a moderator or privileged account?

Give me a few days to prepare something. Any one who has seen some of my guides knows that I number each step and add general comments to explain what is going on and I see this being no different and I want to ensure I'm covering all the basics.

We should also come up with a list of troubleshooting guides which should be created. Of course someone will need to be comfortable in writing the guide and I personally do not want to get into anything really complex. I think one called "System Burn-In Testing" or some similar title would be a good guide too since we may reference someone to run those basic tests like MemTest86 or MemTest86+, some CPU burn-in, etc... This should keep folks busy for a while.

 

[BigDave]

I applaud any efforts and ideas that make things easier for folks to use and troubleshoot
FreeNAS. I wish to point out one observation when it comes to answering much of the
same type questions (repeatedly) in the forums. I have been in here for a while now and
have noticed the following statement from posters. "I have searched the forum and
couldn't find any posts with an answer to my issue".
Until the day arrives that "the forum search feature sucks" retort, is just a distant memory,
the creation of more guides, how-tos, etc. will benefit only those who learn by reading.
The manual is already too big, so my suggestion is to create Trouble Shooting Section
right here in the forum (and never to be moved) but FIRST concentrate all efforts to fix
the search feature of the current forum or move the forum to a more search friendly venue.

 

[gpsguy]

Will there still be a "great big guide" option in version 10?

I find having an offline version valuable in supporting forum users. And some of us would rather RTFM. ;-)


Sent from my phone

 

[joeschmuck]

I have been in here for a while now and
have noticed the following statement from posters. "I have searched the forum and
couldn't find any posts with an answer to my issue".

Lazy people can't find the threads. Hopefully a section explicitly marked for troubleshooting will help for the most frequent problems. I'd be foolish to think we can solve every problem but hopefully most of the easy ones.

 

[dlavigne]

Nope. Just the Documentation section of the forums and the built-in help.

 

[dlavigne]

OK, forum created. I made you the moderator of it. Lord knows if the permissions are correct so let me know if you can't post or if you see other people posting who shouldn't and I'll try some more permission wrangling.

 

[joeschmuck]

I've got something started now but yesterday I spent some time playing with my new internet radio. Maybe today I can finish up the hard drive troubleshooting and then some folks can look it over for corrections.

I'll look into that forum later today to see if I can access it. Thanks.

 

[joeschmuck]

I posted two threads. I would appreciate feedback and if someone has recommended changes, if you have privileges to change it, go ahead, otherwise just toss me a message at joeschmuckatelli2016@hotmail.com and I'll respond eventually. I just established this email address explicitly for the FreeNAS forums use, I consider it disposable.