SOLVED Is the User Guide supposed to not tell you what anything *is*?

Obi-Wan

Dabbler
Joined
Dec 28, 2018
Messages
17
The title probably comes off as whiny, I don't mean it to, but I didn't find a different way to word it.

I'm new to FreeNAS and NAS/Networking/Storage/Backup/etc. in general. I'm learning a lot fairly quickly, but there are many things and terms that I still don't understand. I'm fully aware that there is a lot of stuff that I don't know and that I need to spend a lot of time learning, I can't expect anyone or any single document to hand me everything on a silver platter.

Still, when I search around the forums I often see people referring others to the User Guide. This often makes sense if you are wondering about how to do something, but I generally find it makes very little sense when wondering about what something is or how something works.

What prompted me to write this post was that I was thinking about setting up snapshots. Again, the User Guide can tell me how to do this, but I'm not able to read from the guide what these snapshots actually are and how they work. To me this seems like very useful information!

After searching around a bit I found this post and this post that more or less explain how they work. In one of them danb35 complains he has seen other threads about misconceptions around snapshots as well. So why isn't this information in the User Guide? Is it supposed to be more of a cookbook?

I understand that things take time and know full well from my own job that writing documentation isn't exactly top priority. But for me, as a complete stranger in this new field, the User Guide comes off as lacking, and this makes me wonder if it is so on purpose. Not that it is lacking on purpose, but that it doesn't contain this kind of descriptive general information on purpose. Perhaps because most FreeNAS users are not complete newbies like myself? I don't know.

Again, I don't want to complain about the User Guide, I just really feel like I'm missing something! (Which, admittely, could just be experience!)
 

Chris Moore

Hall of Famer
Joined
May 2, 2015
Messages
10,080

Obi-Wan

Dabbler
Joined
Dec 28, 2018
Messages
17

Thank you! I had indeed missed the ZFS primer, which contains a lot of useful information.

I still think the User Guide is written a way that is not the most useful for beginners. The link to the ZFS primer should really be in the very first part of the User Guide introduction, not hidden away. The same goes for snapshots. The information could definetly be organized a way that is less confusing for beginners, and if it is possible to contribute to that, I'm all ears!

It think it helps me change my mindset and think of FreeNAS as something that allows me to use ZFS and then I need to read up on ZFS instead of reading up on FreeNAS. Perhaps that is what I felt I was missing! In any case, I do feel less puzzled now and hope these thoughts can be useful for some other soul who is also feeling a bit lost ...!
 

Chris Moore

Hall of Famer
Joined
May 2, 2015
Messages
10,080

Obi-Wan

Dabbler
Joined
Dec 28, 2018
Messages
17
Are you saying that you want to work on the project?

Depends on how it works. Right now I'm in the situattion where I see very clearly, I think, where it would be useful to add a small link or a tiny additional piece of information that would be very helpful for beginners like myself. It depends on how rigid the User Guide editing procedure is.
 

Redcoat

MVP
Joined
Feb 18, 2014
Messages
2,925
It think it helps me change my mindset and think of FreeNAS as something that allows me to use ZFS and then I need to read up on ZFS instead of reading up on FreeNAS.

I had this same experience, though I think my expectations of the User Guide were not as "stringent" as yours after close to 40 years of buying "foundation material" books to understand what was/is "under the hood" of an OS (and motor vehicles, too, for that matter - though that's closer to 60 years...).
 
D

dlavigne

Guest
Depends on how it works. Right now I'm in the situattion where I see very clearly, I think, where it would be useful to add a small link or a tiny additional piece of information that would be very helpful for beginners like myself. It depends on how rigid the User Guide editing procedure is.

It works like any other github project where contributors submit PRs: https://github.com/freenas/freenas-docs/blob/master/README.md.
 

Obi-Wan

Dabbler
Joined
Dec 28, 2018
Messages
17
I will mark this as solved now because I think I have landed on an answer, at least for myself. And the answer is mostly yes, the User Guide is in fact not meant to tell you what everything is. But this is not a problem at all.

In case someone stumbles across this I will add that if you are like me and have a rough idea about what you want to do, and you have read about FreeNAS and what it can do, and you are a bit impatient and want to get it running perfectly really quick, then you can't expect the User Guide to explain everything for you. You need to get a decent grasp of what ZFS brings to the table and how it works, and you need to get an idea about the different FreeNAS features you will want to take advantage of.

A suggestion of things to read/follow to get a good start:
There is tons of stuff to read, but I feel this gives a good and somewhat focused start.
 

Chris Moore

Hall of Famer
Joined
May 2, 2015
Messages
10,080
Top