Register for the iXsystems Community to get an ad-free experience and exclusive discounts in our eBay Store.

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

morganL

Captain Morgan
Administrator
Moderator
iXsystems
Joined
Mar 10, 2018
Messages
252
Thanks Stilez, Ornias

The major changes I see are that you want more topics at the top level...which is more like a traditional manual. This can be done progressively.

As a start, we could add "ZFS Storage" as a top level topic...its a peer of "Sharing". This makes it easier to add advanced topics.

I'm also open to adding a "Basic Concepts" section... after we have sufficient content. In the meantime we could start a "Concepts" page in "Overview".

The "Common recipes" i'd prefer to keep as part of "Initial setup"...... we have too many users that want to do multiple things and hence need a generalized setup advice. However, adding a how to on "Setting up a Media server" would be useful.

Morgan
 

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
459
Thanks Stilez, Ornias

The major changes I see are that you want more topics at the top level...which is more like a traditional manual. This can be done progressively.

As a start, we could add "ZFS Storage" as a top level topic...its a peer of "Sharing". This makes it easier to add advanced topics.

I'm also open to adding a "Basic Concepts" section... after we have sufficient content. In the meantime we could start a "Concepts" page in "Overview".

The "Common recipes" i'd prefer to keep as part of "Initial setup"...... we have too many users that want to do multiple things and hence need a generalized setup advice. However, adding a how to on "Setting up a Media server" would be useful.
The reason for a flatter wider top level is that if you don't, you aren't helping anyone. You're just forcing then to open 2 menu levels instead of one, to get to whatever they want.

As a bonus, they are also forced to guess where the material they want is located because you've had to crush disparate or logically separable things into the same top level sections to do so ("round pegs in square holes").

The rationale for the menu structure I suggested was this. See if you agree.

  1. Everyone needs basic concepts - to not screw up pool design, to comprehend core information needed.to.run the platform. That's applicable to everyone. Basic concepts is wider than just ZFS, as you can see from the subtopics, but also splits logically into chunks.
  2. Once you have basic concepts, the next easy tranche to deal with is the kind of user who says "I just wanna X, how do I do it?" That kind of user doesn't want detail first, they want to go direct to solutions. So let them. They can always read specific other stuff when needed. So next, all your "one stop shop" solutions.
  3. All solutions need a basic setup, so I make basic setup the first recipe, and for all the others make step one "set up the basic server (see recipe 1)". This positions basic setup as simply being the first recipe.
  4. Extending via jails/plugins/VM is a neat chunk - all of these have in common "This is how to set it up, after that its up to you". Keep that as a top.level chunk on its own, as a peer to basic recipes and full details.
  5. Last, your users who want to set it up "as they want it", or are technical, or want to set up something more individual/specific. These users are more likely to be willing to read the detail, and want that detail. They are the ones who need the deeper coverage by area. But if you bury all that within "Advanced use" all you are doing is annoyingly forcing them to open 2 levels instead of 1 every single time....... and trust me, that gets *really* annoying *really* fast.
  6. Its also pretty condescending to users, to label non-advanced stuff as "advanced", it can come over as if all but elite users dont need to worry their heads about the arcane controls in "dataset options", whereas many will be interested in compression, dedup, encryption and so on. Its also incredibly vague and therefore unhelpful as a title. So I label them as what they are - "Technical and in depth", or "Managing your pool and its data". *Not* just "advanced".
 
Last edited:

morganL

Captain Morgan
Administrator
Moderator
iXsystems
Joined
Mar 10, 2018
Messages
252
There is a tradeoff in the visual layout when you have too many top levels and use the modern style.... we have 7 top levels right now. Adding a couple is reasonable, but more would require a major change in graphical layout....... won't be done in this cycle. We'd prefer to focus on completeness of content. Names can be adjusted once we have the top level optics settled. Lets discuss on slack..
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
469
I'm very busy right now, But I want to add a bit:
Thanks @morganL for thinking with us and agreeing the ZFS content is a good one to put on top level. This change should already clean things up significantly and I expect the storage/zfs related content to grow expodentially and even surpass the initial setup menu eventually :)

I agree that there should be a balance between the amount of top-level items and levels.
I don't think everything should be on top level either, some very-seldome used things could just as well be another layer.
It's also VERY understandable that you aren't going to fully re-itterate on the layout.

That being said:
I was viewing the side on my wifes 1080p screen yesterday... and you might want to give the left-side menu another 10-20% width. It doesn't "fit" very well with the 2-3 layers depths, because every layer adds another indentation.
*edit*
I took a quick other look: The issue is really just with with lower resolutions, maybe just don't show the right hand menu below a certain resolution and give some more room for both text and left-side menu? I think that would solve all readability issues on lower-res.
 
Top