Despite having used FreeNAS for the better part of 5 years I still consider myself an utter beginner compared to the demi-gods that roam the halls here. Every time I start to branch down a new FreeNAS feature hallway (VMs, ACLs, whatever), I rediscover my ignorance re: all the details that make up FreeNAS. While mostly complete, the current the "
Brockhaus"-style 11.3 encyclopedic documentation is filled with hard facts but it frequently doesn't show the
process of putting that information to work.
Hence, I fall back on the forum to ask for help for critical implementation details that I don't really consider that uncommon for someone trying to do something allegedly supported by FreeNAS/TrueNAS. Let's take VMs as an example, i.e.
how to make a extra hard drive show up in a Windows VM,
how to adjust tuneables to allow for more than 2 cores being allocated to the VM, etc. I found
@Yorick's Youtube guide to installing a Windows 10 VM to be a great guide.
Hence, I have been advocating for two sets of information: A continuation of the encyclopedia as seen in 11.3.x as a reference to fall back on to explain terms used in document tree #2, which is the how-to guide that IXsystems seem to be developing for 12.x. I suggest these two document trees grow in parallel, with links peppered throughout the how-to 12.x documentation back to the encyclopedia. Pepper those 12.x how-to guides with plenty of hyperlinks and hopefully, this will give the team the opportunity to develop clean-looking documents yet cover details in-depth for power users.
That approach not only allows the re-use of 80%+ of the information already invested in the current encyclopedia but it also allows the documentation teams to generate really relevant guides on common topics. I'd break them up into bigger sections - for example, one whole site / document dedicated to educating users about use case, pool layouts,
what components to select for each use case and why before buying hardware.
People are not coming TrueNAS for the fastest I/O experience (a dedicated hardware RAID will likely give that to you) they are coming for battle-hardened, proven data integrity. So let's make pre-deployment planning as comprehensive as possible so the resultant experience is as pleasant as it should be. Yes, this is something the specialists in the technical sales department at IXsystems do every day, but if you want that to scale, you need a better document. Not everyone has the time, budget, etc. to interact extensively with the sales team. Plus, at the entry level, there are few choices.
Similarly, go into the details of various protocols ahead of time so the so-to-be admin can benefit from the aggregated knowledge here re: hardware, software configuration, etc. before standing up a server. There is a lot of information to mine in the forum and in the various resources that the user base has put together. Again, focus on use cases (ex. how how someone with a lot of VMs might benefit from dedups, special hardware, etc. to make FreeNAS sing).
The next section should be a how to guide for a simple initial setup to allow the user to verify their hardware (i.e. cover burn-in, etc. which really should be a GUI feature IMO), add users, set up a simple share, etc. Then have separate pages dedicated to each protocol. How to set up a VM in detail, for common platforms (Windows, Linux, etc.). Similarly, the various jail experiences could be documented a lot better.