SOLVED TrueNAS 12 docs in awful condition compared to 11.3 - can't IX do something?

Status
Not open for further replies.

Evertb1

Guru
Joined
May 31, 2016
Messages
700
So what is the point of even writing open source software if there isn't adequate documentation to actually use it?
That's up to the builder of the software I think. They make their own plans an deside on their own priorities. That's the reality.

Personaly I disagree with the way iXSystems handles the manual. In their place, I would have upgraded the old documentation so there was at least a usable manual. That would take away some of the heat of a big release. And then, when the pressure from that coming release was over, working on a project to port the manual to another platform and reformat/reorganize it. But that's just me.
 
Last edited:

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
@Evertb1 I agree, I don't mind the manual and format of the manual changing. I'm not against change for the sake of change.
But it should be:
1. An improvement
2. Have content parity.

Both tests fail:
1. The current example has a menu structure that is less useable/quick/easy
2. Due to 1 it is hard to evalute because one can't find jackshit. But, some people report not all content is ported yet.
 

danb35

Hall of Famer
Joined
Aug 16, 2011
Messages
15,462
Your vague topics in fact *need* that detail.
Hmmm. Seems like someone else mentioned that too. Ah yes:
Each of those steps has dozens of options, and most can, in most cases, safely be left at their defaults (if the defaults weren't good enough, they wouldn't be the defaults, right?). But the reason you've exposed those options is that you expect users will, at least occasionally, need to change them, and that means they need to be documented.
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
Okey, Sometimes something bad needs to be said (like before) and sometimes something good:

- It looks like IX has at least fixed some of the readability issues that plagued the menu :)
 

VladTepes

Patron
Joined
May 18, 2016
Messages
287
Here's my take on the OP - TL;DR - I completely agree.

As a user with some experience of FreeNAS I know just enough to be dangerous (and little else). If there are any changes in TrueNAS core with the potential to stuff me up then I NEED to know about them.

Further - If I was a potential new user looking around for a NAS solution I'd be extremely unlikely to choose a product where there is no simple to follow manual and step-by=step "how to" things to get me up and running. So I'd probably end up with some bloody synology rubbish instead.

If I were a potential business customer I'd still almost certainly try the free core version first and if I had a bad experience in setting that up I'd be looking elsewhere.

When the whole FreeNAS -> TrueNAS Core thing was announced, we were assured that things would continue to be awesome.
I hope this lack of a comprehensive, updated manual for the new product isn't indicative of things to come.
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
If there are any changes in TrueNAS core with the potential to stuff me up then I NEED to know about them.

Don't worry, not anything that isn't already part of FreeNAS :)

Further - If I was a potential new user looking around for a NAS solution I'd be extremely unlikely to choose a product where there is no simple to follow manual and step-by=step "how to" things to get me up and running.
That was what I personally liked about the old manual: I just walked through every option and evaluated if I needed it and when on the bottom of the menu I was done. Easy peasy, no 600 dropdowns deep... :P

When the whole FreeNAS -> TrueNAS Core thing was announced, we were assured that things would continue to be awesome.
I hope this lack of a comprehensive, updated manual for the new product isn't indicative of things to come.

The product is fine, really it is. The UX team is doing great work there, the OS team has been doing great work on ZFS and so forth.

The problem seems to be more the Docs team also managing the UX for the docs, seperately from the UX team itself. Although as I concluded in my previous post: They did improve things already and added A LOT of pages last week. It seems they did hear the pressure to perform and did do so.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
Okey, Sometimes something bad needs to be said (like before) and sometimes something good:
- It looks like IX has at least fixed some of the readability issues that plagued the menu :)

Thanks for this. Indeed, much improved. Thank you IX.

That said, it's important that the docs/info library is consistent and the same information findable whatever entrypoint you use. But it isn't. It's completely different depending what entrypoint you use, and in some entrypoints the current version guide cant be found (or I couldn't find it) in the docs at all.

Example:

If you click "Guide" in the WebUI, you get a completely different experience than if you click "support->information library" on the website home page and look for the TrueNAS 12 CORE guide. On the latter page the new guide layout can't easily be found, in fact if you've heard about TrueNAS 12 CORE (successor to FreeNAS) and try to find its guide, you can't, or at least I couldn't. I've noted this as DOCS-1124, asking IX to check all entrypoints do have consistent and usable UI, and the docs one would expect to find can be found on each.
 
Last edited:

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
Here's my take on the OP - TL;DR - I completely agree.

As a user with some experience of FreeNAS I know just enough to be dangerous (and little else). If there are any changes in TrueNAS core with the potential to stuff me up then I NEED to know about them.

Don't worry, not anything that isn't already part of FreeNAS :)

@VladTepes - You're right to be concerned, and AFAIK unfortunately on this occasion @ornias may be incorrect (although usually is spot-on!).

Crossref for example this recent forum post, and the posts after it, as one example:

Q: "How do i remove the special metadata vdev? I tried using the GUI, it threw an exception. (USING TN CORE RC1)"
[Posts output of zpool status -v, shows they used RaidZ for the main pool]​
A: "This is the output of the info for man zpool-remove, the command used to remove disks and vdevs from a pool. My emphasis added: "When the primary pool storage includes a top-level raidz vdev only hot spare, cache, and log devices can be removed". The Web UI threw an exception because the underlying command failed, although admittedly it should have handled it more gracefully. But the failure is genuine, not a bug. You can't just remove the special vdev, as best I know, because of that restriction. You'd have to rebuilt (replicate) the pool.​
Q: "Ok thanks. Then why did someone on this post say you can remove it? I am getting contradicting info lol."
A: "Because not everyone, even the best intentioned, reads all the small print on man zpool-remove. Honest mistake, special vdevs are new in this version and its easy not to know the detailed limitations that can apply to removal."​

Thats a simple example.

Another is the person who from memory nearly lost their encrypted pool trying to upgrade from 11.3 GELI based, to 12.0-RC native encryption, or some such.

With much respect to Ornias, who is highly experienced and usually spot on, with the huge changes between v11.3 and v12, I disagree. There are probably plenty of other changes and individual scenarios that would screw a user up, or at the least cause them issues, if not made clear. That goes double for people who never used 11.3 and are highly reliant on the provided/linked guide/docs to help them know what to do and how to make good choices.

Those are severe cases, but for every severe case, I expect there are hundreds of people who are stressed by which options to choose, or take days to find working option choices, or end up with suboptimal options and config, because while the v11.3 docs had much of the information for that sort of thing and it previously existed, it's now ripped out in v12, and so the v12 docs didn't help.

v12 docs are far from "fit for purpose", yet.
 
Last edited:

HoneyBadger

actually does care
Administrator
Moderator
iXsystems
Joined
Feb 6, 2014
Messages
5,110
Crossref for example this recent forum post, and the posts after it, as one example:
I was thinking of this exact post.

There are already a number of instances where a user has accidentally added a single drive in striped mode, thinking this is the equivalent of "RAIDZ expansion" or is incorrectly using cache/log devices - adding the special devices such as meta/dedup into the mix adds a number of potential ways someone can put themselves into a situation where the fix is "back up and rebuild your pool"

At the very least there should be documentation with very clear warnings of "You may be about to paint yourself into a corner."
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
@Stilez
You're right, my comment wasn't on-par with my normal quality guideline, I totally read his post wrong:
"If there are any changes in TrueNAS core with the potential to stuff me up then I NEED to know about them."

I read it as "Which would bite me in the ass when updating my current pool"

which wasn't what he meant, he clearly meant "anything at all in the release that could screw me over", which indeed: Just like any vdev, even special vdevs might destroy your data if handles wrong.
Those two issues are not data-destructive though, a cascade of user error including those might be though. But there is only a limited amount of handholding IX could do...
 

HoneyBadger

actually does care
Administrator
Moderator
iXsystems
Joined
Feb 6, 2014
Messages
5,110
I don't know about "handholding" but "guidelines" definitely need to exist. A user error that can be corrected via a GUI or CLI command is one thing - a user error that leads to "whoops, you have to back up your entire pool and recreate it" is a little more severe.

That's not to say that resources don't exist here in the forums for build guides, pool information, etc. But it often arrives too little, too late - users often only register here when they have a problem, and promptly find out that the haphazard collection of drives behind a RAID controller is a horrible idea and there's no way out. What that comes out as in the user's mind is "FreeNAS is bad" or "the userbase is mean because they told me an uncomfortable truth"

Guidance should be provided - but it's also important to know that it's not (and never can be) totally exhaustive. You can make some templates and basic recipes:
"Avoid SMR. No, you can't use your RAID card. USB sticks aren't good enough anymore."
Home media? Get six drives, put them in RAIDZ2.
Performance? Use mirrors.
VMware for iSCSI/NFS? Get a good SLOG unless you're okay with data loss.

But like any cook, you've got to be able to make your own adjustments. And if you aren't confident - there could be a fill-in-the-blank template that can be copy-and-pasted into the forum here with "here's what I want to do" and people can answer. Or if this is business-critical - pay a consultant for their time.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
@ornias - you've had the closest look at this of anyone, excepting IX staffers, and I get the impression backed off because while docs conversion was technically easy, other aspects were a mess.

Given that ultimately, we all aim to be solution based and not just hand-wring at the problems, I have given some thought to how we might at least improve it from here.

I've ended up with a few questions for you, to clarify my thinking, as someone who takes it seriously and has looked hard. (But comments/answers from IX staff or indeed anyone else, also welcomed please!!)
  1. How much work is involved in simply migrating the 11.3 text to another format, whether that used in the new docs hub or any other kind of reasonably popular markup/markdown?
  2. Once that's done, how much do you feel has changed, between 11.3 and 12?
  3. Last, breaking (2) down into sub-questions. Assuming its clearly marked as a work in progress and not presented as final, perfect or IX-official, and assuming sections that have still to be uodated are also clearly marked, how much do you reckon *has* to be updated, in order to (A) remove stuff in 11.3 that would be wrong in 12, (B) add stuff that *must* be explained to configure 12 without huge screwups and issues, and (C) address Web UI or operational info that is totally new or so different that the 11.3 docs effectively are worse than useless and need the entire chunk rewritten for the new stuff?
In effect, suppose we aimed to create something that covers most of it reasonably well, some marked lapses "to be done" or "ask in forum" for now, and enough that the areas which could cause major problems are clear at least.... good enough not perfect.....

If that's all we aimed for, and we didn't care if it was long pages as before, or docs hub breakdown, as long as it could be *used*.....

How much work does *that* involve, do you think?

Tl;dr:

IX isn't going to do it or at least in no timely manner, community can't do it within IX way of working due to lack of needed/requested assistance and focus from IX as described.

Suppose for now we go ultra pragmatic, and say "stuff the ego" and set aside all questions who "ought" to do what, what IX should be helping/doing, whether the output is or isnt in a format IX would want, and what IX paid customers should expect of IX docs.

Suppose instead we simply agree that the important thing and best all round for now, is *somehow* to have available *some* kind of comprehensive-ish, serious-error-avoiding v12 info, in any format, by any author/s, even if its the same old long stuff or crudely cut into chunks.... As long as its usable and timely. Then at least its tenable as a holding position.

How much work would it take to do that, do you think?

To get something not too f**ked up but at least *usable* and timely as a guide *somehow*, on any workable terms and output format, via minimal work as achieves those barest key goals, and via any process, that is adequate at least for now?
 
Last edited:

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
@ornias - you've had the closest look at this of anyone, excepting IX staffers, and I get the impression backed off because while docs conversion was technically easy, other aspects were a mess.
Yes mostly, I went over it and got the feeling 80% of the old manual was already there... just not as easy to find, which also made it hard to say for sure what was and wasn't moved over.

Given that ultimately, we all aim to be solution based and not just hand-wring at the problems, I have given some thought to how we might at least improve it from here.

I've ended up with a few questions for you, to clarify my thinking, as someone who takes it seriously and has looked hard. (But comments/answers from IX staff or indeed anyone else, also welcomed please!!)
Always open for questions and suggestions

  1. How much work is involved in simply migrating the 11.3 text to another format, whether that used in the new docs hub or any other kind of reasonably popular markup/markdown?
To get a 90% efficient translation (mostly some boxes around paragraphs and some links that need fixing), I can asure you no effort is needed.
Why? I already have it for ya ;)

2. Once that's done, how much do you feel has changed, between 11.3 and 12?

Mostly added features, the major features aren't changed that much. VM's are still VM's, jails are still jails, plugins still work most of the time(tm) and shares/permissions are still a pain. GUI is though, but thats just going through the image folder one by one and making new screens.

3. Last, breaking (2) down into sub-questions. Assuming its clearly marked as a work in progress and not presented as final, perfect or IX-official, and assuming sections that have still to be uodated are also clearly marked, how much do you reckon *has* to be updated, in order to (A) remove stuff in 11.3 that would be wrong in 12, (B) add stuff that *must* be explained to configure 12 without huge screwups and issues, and (C) address Web UI or operational info that is totally new or so different that the 11.3 docs effectively are worse than useless and need the entire chunk rewritten for the new stuff?
Mostly screenshots actually and documentation for added features like special allocation classes. Mostly just GUI restructure (see 2) and formatting fixups (see 1.)


But:
I think you're wrong in your priorities:
1. We need a clear (and expandable!) layout: What needs to go where, how many layers deep and document it (HINT HINT docsteam ;-) )
2. After doing so we need to make a table with three sections:
Layout 3.0 (see 1) | Page within new docs | page within old docs

We need such a table to reference which data is actually missing from the new docs to know what needs and what doesn't need adding.
3. We can easily create a [WIP] version in the new docs from the old docs data using the MD's I already generated :)

TLDR:
The problem isn't migrating the data "want it PR'ed tomorrow into it's own tree? Have it tomorrow!", I can use ctrl-c ctrl-v and scripting myself.
No the real problem is STRUCTURE. What data needs to go where and/or do the docs already contain a certain page
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
Yes mostly, I went over it and got the feeling 80% of the old manual was already there... just not as easy to find, which also made it hard to say for sure what was and wasn't moved over.


Always open for questions and suggestions

To get a 90% efficient translation (mostly some boxes around paragraphs and some links that need fixing), I can asure you no effort is needed.
Why? I already have it for ya ;)



Mostly added features, the major features aren't changed that much. VM's are still VM's, jails are still jails, plugins still work most of the time(tm) and shares/permissions are still a pain. GUI is though, but thats just going through the image folder one by one and making new screens.


Mostly screenshots actually and documentation for added features like special allocation classes. Mostly just GUI restructure (see 2) and formatting fixups (see 1.)


But:
I think you're wrong in your priorities:
1. We need a clear (and expandable!) layout: What needs to go where, how many layers deep and document it (HINT HINT docsteam ;-) )
2. After doing so we need to make a table with three sections:
Layout 3.0 (see 1) | Page within new docs | page within old docs

We need such a table to reference which data is actually missing from the new docs to know what needs and what doesn't need adding.
3. We can easily create a [WIP] version in the new docs from the old docs data using the MD's I already generated :)

TLDR:
The problem isn't migrating the data "want it PR'ed tomorrow into it's own tree? Have it tomorrow!", I can use ctrl-c ctrl-v and scripting myself.
No the real problem is STRUCTURE. What data needs to go where and/or do the docs already contain a certain page
Ive dropped a couple of questions for you in user conversations, to check where this might be at.
 

KevDog

Patron
Joined
Nov 26, 2016
Messages
462
Your passion over the documentation is actually commendable. I know nothing about the 12.0 documentation. I'm pretty familiar with the 9,11 documentation. I can't say I've never consulted the manual about things, but honestly most of the answers I have about options and such, particularly ZFS related material -- does not come from Xi systems or their documentation but other websites. Old documentation listed options, however seemed to touch upon concepts superficially. I suspect the new documentation will be equivalent. So in terms of specifics, I'd say it wasn't specific enough. In terms of general concepts and how-to's --- isn't that what the forums are for? There are some pretty good user submitted tutorials in the forums and they are enjoyable to read. The comments of how people screw up the tutorials or want to tweak the instructions for a specific use case are pretty informative as well. I honestly don't know how you would capture this detail in documentation.
 

morganL

Captain Morgan
Administrator
Moderator
iXsystems
Joined
Mar 10, 2018
Messages
2,691
There's been some progress made on structure, but there will always be opinions on how to layout. At the 1st level we have:

Overview
Initial Setup
Sharing
Advanced Management
Solution Integrations

Within initial setup... there are many sections including configuring storage.

There is a new lefthand side menu to emulate browsing a document. See this storage page as an example:
https://docs.ixsystems.com/hub/initial-setup/storage/

Any strong views on how to improve this 1st level?
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
Any strong views on how to improve this 1st level?
I noticed the change in font before, that helps a LOT.

I would like to see more catagorised into the first level, for example: "Initial setup", should be limited to the content of "install" and "initial config".
For example: The complete storage config seems at the wrong place there (should be moved to root level, just like sharing) and so are more things.

The section stating this, is now above the navigation on the right side, on smaller screens this pushes the navigation into "almost not visable":

All contributors welcome! Learn more about making documentation changes

I sadly don't have to time to go over it fully, as my current train is about to arrive, I'll try to get you my other work and a short overview of structure this weekend.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
There's been some progress made on structure, but there will always be opinions on how to layout. At the 1st level we have:

Overview
Initial Setup
Sharing
Advanced Management
Solution Integrations

Within initial setup... there are many sections including configuring storage.

There is a new lefthand side menu to emulate browsing a document. See this storage page as an example:
https://docs.ixsystems.com/hub/initial-setup/storage/

Any strong views on how to improve this 1st level?
3 observations immediately come to mind, I've commented on the top level menu structure separately below to keep that separate.

1) CONSISTENCY OF ACCESS

If you look for the v12 docs such as they are from the webUI you get one presentation. But if you want to browse the v12 docs from the I systems website "support" link, its called something completely different ("technical library? Info hub?). The appearance, the layout, the findability, even the title itself, are a real problem as they vary dramatically depending how you access the docs.

I'd suggest now that the side menu is fixed (thank you!!) I would look at the different entrypoints to the docs/technical library/info hub/guide. I'd try to ensure they are uniform, and that however you find the provided support info, the format is similar, findability is similar, the nomenclature is similar (is "technical library" the same as "documents hub" and if not, what's the difference?). If your link took you to one specific section of the documents (eg "v12 guidance") make sure theres always a clear link to the top level entrypoint of the entire.support info/docs hub/technical.library/whatever its called, and so on.

That kind of consistency really makes.a difference in UX.

2) HOW THE NEW DOCS HUB IS ENVISAGED TO WORK IN PRACTICAL TERMS

I'm still struggling a bit to understand how IX envisages its docs.

Clearly there needs to be guidance *somewhere* about each screen, each option, and about "what you need to know about [X] before using that capability/option". Whatever its called, however its packaged and organiseed. Call that a functional description, which goes down the capabilities, screens and options, explaining how they work and what they do.

IX seems to want to move to a task based list, "how to create a pool, how to do X", and I'm having real difficulty seeing how that doesn't become the same thing in the end, with lots more repetition/duplication.

After all, to do 'initial setup" you need to understand how to choose a pool design, pros and cons of different designs, hardware demands that different options might imply, and what each different control and option does, within the "create pool/dataset/zvol" UI and their options.

That's effectively the same functional "what does X do" information as above/before, and its clearly not.possible to substitute it by vague recipes without that level.of understanding. The entire system has options, and users need that info.

So I feel your task based thing perforce either remains vague and unhelpful, or else degenerates into a thin extra layer on top of the 11.3 style of info.

If you could clarify this, it would help a lot, because I suspect few of us can envisage how IX plans it to work in day to day usage. For example, in your task oriented docs, where is it envisaged one goes, to find what the "sync/async" setting does, or implications of different pool structure choices, or case sensitivity options in SMB, or some option in the "edit dataset options" webUI, or whatever else it may be? Can you clarify how one is envisaged to find that kind of stuff - and how/where it fits into the structure, in the envisaged docs?

3) FINDING RELEVANT DOCS

Again, the 11.x docs, release notes etc will often be misleading for v12- perhaps damagingly so in some cases. So a way is needed to.specify the kind of doc you want to.search in, for.the search box, not return all hits in all docs. All this needs to be if minimal, is a drop down with checkboxes listing each version, "release notes" and "other documents" for now?
 
Last edited:

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
There's been some progress made on structure, but there will always be opinions on how to layout. At the 1st level we have:

Overview
Initial Setup
Sharing
Advanced Management
Solution Integrations

Within initial setup... there are many sections including configuring storage.

There is a new lefthand side menu to emulate browsing a document. See this storage page as an example:
https://docs.ixsystems.com/hub/initial-setup/storage/

Any strong views on how to improve this 1st level?

SUGGESTED TOP LEVEL DOCS STRUCTURE

I approach this by thinking, what tasks or needs a newcomer comes up against, in order. I added a couple of obligatory bits like "what's new" and "contributing". I get to this kind of structure, and I've filled in 2nd level structure for some of it.

The aim is to cover basic concepts first - these are more arranged as a "how to/task" for each area to.try and match IX's concept. Then common recipes, to make it easy for someone with a typical/common use-case to get set up. If they have the basic concepts, and follow a recipe, they should be able to get going, again much as IX's task concept. Last are detailed how-to guidance area by area, again trying to focus on tasks and issues not just as the 12.x guide did running through the screens. This also provides the detail that an advanced user may need.

  • Intro page
  • What's new
  • Basic concepts:
    • TrueNAS platform overview
    • Key hardware choices/notes (important stuff only, brief, not a full hardware guide, crossrefer elsewhere for that)
    • ZFS concepts
    • Choosing a basic data pool structure (and pros and cons of different structures)
    • Choosing and using special devices - slog, l2arc, special vdevs, spare disks
    • Other important pool choices - encryption, dedup, compression, sync/async, case sensitivity and other common options covered. Either as separate topics at 2nd level or umbrella-ed together as 3rd level topics
    • High performance tips (this is an extremely common wish so have a section on it! It'll get noticed!!)
  • Common situations and recipes
    • Basic setup
    • Setting up a media store and server
    • Setting up a basic file server with file history
    • Creating a VMware ESXi (and similar) store/server
    • Other?
  • TECHNICAL AND IN-DEPTH GUIDANCE, AND ADVANCED USES:
  • Managing your pool and its data
    • Datasets and zvols
    • Snapshots (including snapshot periodic tasks) and checkpoints
    • Backing up and replicating your pool
    • Error checking your pool with scrub
    • Expanding a pool or mirror
    • Removing a mirror, top level vdev or.cache device
    • Pool configuration changes (adding or removing dedup compression encryption ACLs etc, after pool created)
    • Renaming a dataset, zvol or snapshot
    • Rebuilding a pool (not quite the same as backup/replication, more like when you might need to, and how to approach it)
  • Sharing data
  • Platform management
    • Administration and control
    • Networking
    • Updating
  • Expanding the platform with jails, plugins and virtual machines
  • Advanced capabilities
    • VMWare integration
    • Solution integration
    • High availability/clustering info if any
    • Other?
  • TROUBLESHOOTING, HELP & SUPPORT, AND FEEDBACK
  • Troubleshooting and known issues and workarounds
  • Contributing improvements and suggestions to.the platform or its documents
  • Help and support
 
Last edited:
Status
Not open for further replies.
Top